CDQ Insights API - Time Granularity - Trend Analysis

Overview

This tutorial shows you how to use the timeGranularity parameter to retrieve metric values over time, understand the three granularity modes and when to use each, and build a trend view of your data quality ratio across months.

This tutorial builds on Fetching a Metric with Postman and Filtering and Dimensions. You should have the CDQ Insights API collection in Postman.

Learning Goals

In this tutorial, you will learn how to:

Use the timeGranularity parameter to return values over time
Choose between the DAY, WEEK, and MONTH granularity modes
Understand how dateTo is represented in week and month modes
Combine time granularity with dimensions to build per-group trends

Why time granularity matters

In the previous tutorials, every request returned a single result: the latest calculated value within your date range. That is useful for a snapshot ("what is the state of my data today?") but tells you nothing about how things are changing over time.

The timeGranularity parameter changes this. Instead of one result, the API returns one result per time bucket (a value per day, per week end, or per month end), letting you track trends, spot regressions, and measure improvement over time.

The three granularity modes

Mode	Behaviour	Best used for
(not set)	Returns the single latest value in the requested range	Snapshots, current state
`DAY`	Returns one value per day in the range	Daily monitoring, short date ranges
`WEEK`	Returns one value per Sunday in the range, plus the `dateTo` date if it is not already a Sunday	Weekly reporting
`MONTH`	Returns one value per month-end date in the range, plus the `dateTo` date if it is not already a month end	Monthly reporting, long date ranges

In week and month modes, the API always includes the dateTo date in the results even if it does not fall on a Sunday or month end. This ensures your end date is always represented, which is useful when your report period ends mid-week or mid-month.

Step 1: Daily granularity

Let's fetch the data_quality_ratio for each day across a two-week window.

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-14",
    "timeGranularity": "DAY"
  }'

The response now contains one result per day:

{
  "items": [
    {
      "id": "data_quality_ratio",
      "results": [
        { "date": "2026-05-01", "value": 0.9388 },
        { "date": "2026-05-02", "value": 0.9391 },
        { "date": "2026-05-03", "value": 0.9391 },
        { "date": "2026-05-04", "value": 0.9405 },
        { "date": "2026-05-05", "value": 0.9405 },
        { "date": "2026-05-06", "value": 0.9412 },
        { "date": "2026-05-07", "value": 0.9412 },
        { "date": "2026-05-08", "value": 0.9412 },
        { "date": "2026-05-09", "value": 0.9418 },
        { "date": "2026-05-10", "value": 0.9418 },
        { "date": "2026-05-11", "value": 0.9418 },
        { "date": "2026-05-12", "value": 0.9421 },
        { "date": "2026-05-13", "value": 0.9421 },
        { "date": "2026-05-14", "value": 0.9425 }
      ]
    }
  ]
}

Daily granularity works well for short date ranges. For ranges spanning several months, consider using WEEK or MONTH to keep the response size manageable and the trend easier to read.

Step 2: Monthly granularity

For a longer view that tracks how data quality has evolved over several months, use MONTH. The API returns one value per month-end date within the range, plus the dateTo date if it falls mid-month.

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-01-01",
    "dateTo": "2026-05-31",
    "timeGranularity": "MONTH"
  }'

The response returns one value per month end:

{
  "items": [
    {
      "id": "data_quality_ratio",
      "results": [
        { "date": "2026-01-31", "value": 0.9201 },
        { "date": "2026-02-28", "value": 0.9287 },
        { "date": "2026-03-31", "value": 0.9341 },
        { "date": "2026-04-30", "value": 0.9388 },
        { "date": "2026-05-31", "value": 0.9412 }
      ]
    }
  ]
}

This immediately tells a story: data quality has been steadily improving from 92% in January to 94.1% in May.

What happens when dateTo falls mid-month?

If your dateTo is not the last day of the month (for example 2026-05-15), the API includes it as an extra data point alongside the month-end dates:

{ "date": "2026-04-30", "value": 0.9388 },
{ "date": "2026-05-15", "value": 0.9401 }

This ensures your end date is always represented in the results.

Step 3: Weekly granularity

Weekly granularity returns one value per Sunday within the range, plus the dateTo date if it is not already a Sunday.

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",
    "timeGranularity": "WEEK"
  }'

May 2026 has Sundays on the 3rd, 10th, 17th, 24th, and 31st. Since dateTo is the 31st, which is itself a Sunday, no extra date point is added:

{
  "items": [
    {
      "id": "data_quality_ratio",
      "results": [
        { "date": "2026-05-03", "value": 0.9391 },
        { "date": "2026-05-10", "value": 0.9412 },
        { "date": "2026-05-17", "value": 0.9418 },
        { "date": "2026-05-24", "value": 0.9421 },
        { "date": "2026-05-31", "value": 0.9425 }
      ]
    }
  ]
}

Combining time granularity with dimensions

Time granularity works alongside dimensions. Adding country as a dimension gives you a trend per country, which is useful for tracking whether a specific country's data quality is improving or declining independently of the overall workspace trend.

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-01-01",
    "dateTo": "2026-05-31",
    "timeGranularity": "MONTH",
    "dimensions": ["country"],
    "filters": [
      {
        "field": "country",
        "operator": "IN",
        "values": ["DE", "PL"]
      }
    ]
  }'

The response now contains one result per month per country: ten result objects in total for two countries across five months.

{
  "items": [
    {
      "id": "data_quality_ratio",
      "results": [
        { "date": "2026-01-31", "value": 0.9310, "country": "DE" },
        { "date": "2026-01-31", "value": 0.8801, "country": "PL" },
        { "date": "2026-02-28", "value": 0.9388, "country": "DE" },
        { "date": "2026-02-28", "value": 0.8854, "country": "PL" }
      ]
    }
  ]
}

This is the foundation for a time-series chart in a BI tool: one line per country, one data point per month.

Saving your requests in Postman

Save each request in your CDQ Insights API collection:

data quality ratio (daily)
data quality ratio (monthly trend)
data quality ratio (weekly)
data quality ratio (monthly trend by country)

Next steps

The Grouped Endpoint: Snapshot Views tutorial introduces the grouped endpoint, a different way to query the API that returns a snapshot view grouped by one dimension and broken down by another, designed for cross-sectional analysis and dashboard-style tables.

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 - Time Granularity - Trend AnalysisCopy