# CDQ Insights API - Your First Request - Fetching a Metric with Postman

## Overview

This tutorial walks you through your first successful request to the CDQ Insights data endpoint. You will retrieve a real metric value and learn how to read the response, including what to do when the result is a ratio rather than a simple count.

You will fetch the `data_quality_ratio` metric, the proportion of validated business partner records in your workspace that are free from critical defects. A value of `0.94` means 94% of your records have no `WARNING` or `ERROR`-level violations. This metric is a good starting point because it introduces ratio interpretation, the null denominator behaviour, and the "latest value" concept, all of which apply across many CDQ metrics.

**Learning Goals**

In this tutorial, you will learn how to:

- Make your first request to the CDQ Insights data endpoint with Postman
- Read the response structure shared by all metrics
- Interpret a ratio value and understand the "latest value" concept
- Recognise `null` values, empty results, and common error responses


## Prerequisites

- [Postman](https://www.postman.com/downloads/) installed.
- A CDQ API key. If you do not have an API key, contact your CDQ account manager.


## Step 1: Copy the curl and paste it into Postman

Copy the curl below, replacing `YOUR_API_KEY_HERE` with your actual CDQ API key:


```bash
curl -i -X POST \
  https://api.cdq.com/analytics/rest/insights \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "ids": ["data_quality_ratio"],
    "dateFrom": "2026-05-01",
    "dateTo": "2026-05-31"
  }'
```

Open Postman and paste the curl directly into the URL bar. Postman will automatically parse the method, URL, headers, and body, so no manual setup is required.

Adjust `dateFrom` and `dateTo` to a recent period where your workspace has data. If you are unsure, use the last full calendar month. Dates are in `YYYY-MM-DD` format.

The request body tells the API:

- `ids`: which metric you want. Always an array, even for a single metric.
- `dateFrom` and `dateTo`: the date range to calculate the metric for.


## Step 2: Send the request

Click **Send**. You should receive a `200 OK` response. The response body will look like this:


```json
{
  "items": [
    {
      "id": "data_quality_ratio",
      "results": [
        {
          "date": "2026-05-31",
          "value": 0.9412
        }
      ]
    }
  ]
}
```

## Reading the response

The response has a consistent structure across all metrics:

- `items`: an array containing one entry per metric you requested.
- `id`: confirms which metric this result belongs to. Useful when requesting multiple metrics in a single call.
- `results`: an array of result objects. Each object has a `date` and a `value`.


### Interpreting a ratio value

`data_quality_ratio` has a `resultType` of `ratio`, meaning the value is always a decimal between 0 and 1. A value of `0.9412` means that 94.12% of your validated records have no critical defects (no `WARNING` or `ERROR` violations) as of 31 May 2026.

To express a ratio as a percentage, multiply by 100. For display purposes in a dashboard or report, `0.9412` becomes 94.1%.

### What does "latest value" mean?

CDQ calculates metrics daily. When you request a date range without specifying a time granularity, the API returns the most recent calculated value within that range, not an average across the whole period. In this example, you get the data quality ratio as of the last calculation within May 2026.

This is intentional: ratio metrics like `data_quality_ratio` represent the current state of your data, not a running total. Time granularity, that is how to get a value per day, week, or month, is covered in the **Time Granularity: Trend Analysis** tutorial.

### Null values on ratio metrics

If the API returns `null` for a ratio metric, it means the denominator was zero. In this case, no validated records existed for that scope and period. A `null` is explicitly different from a ratio of zero. Zero means all records have defects; `null` means there was nothing to measure.


```json
{
  "date": "2026-05-31",
  "value": null
}
```

This can happen when filtering to a country or data source that has no validated records in the requested date range.

## Troubleshooting common issues

**Empty results array**


```json
{
  "items": [
    {
      "id": "data_quality_ratio",
      "results": []
    }
  ]
}
```

An empty `results` array means no data was found for your request. The most common causes are:

- Your API key is scoped to a workspace with no validated records for the date range you specified.
- The date range is in the future or predates any data in your workspace.
- Try adjusting the date range to a more recent period.


**401 Unauthorized**

Your API key is missing or incorrect. Double-check the `x-api-key` header value.

**400 Bad Request**

The request body is malformed. Check that your JSON is valid (Postman will highlight syntax errors) and that `dateFrom` and `dateTo` are in `YYYY-MM-DD` format.

## Saving your request in Postman

Before moving on, save this request so you can build on it in the next tutorials:

1. Click **Save** in the top right.
2. Give it a name like `data quality ratio (basic)`.
3. Create a new collection called **CDQ Insights API** and save it there.


You will reuse and extend this collection throughout the tutorial series.

## Next steps

The **Filtering and Dimensions** tutorial builds on this request by adding filters to narrow the data and dimensions to break it down, so instead of one overall ratio you get a breakdown by country or data source, letting you see exactly where data quality issues are concentrated.

## Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!