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 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:

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:

{
  "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.

{
  "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

{
  "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:

Click Save in the top right.
Give it a name like data quality ratio (basic).
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!

CDQ Insights API - Your First Request - Fetching a Metric with PostmanCopy