---
title: "Time series"
slug: "time-series"
description: "Learn how the time series adapter expands parallel arrays of metric values into one row per date using the request's date range."
updated: 2026-06-04T07:43:57Z
published: 2026-06-04T07:43:57Z
canonical: "docs.supermetrics.com/time-series"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Time series

Some APIs return parallel arrays of metric values (one entry per day in the requested range) instead of per-date objects. The `time_series` adapter expands those arrays into one row per date, using the request's start and end times to assign each index its calendar date.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `dataPath` | string | Yes | JSONPath to each item that contains a parallel-array metrics object. |
| `valuesPath` | string | Yes | JSONPath, relative to each item, to the object whose properties are arrays of per-date values. |
| `startTimePath` | string | Yes | JSONPath to the request's start time. |
| `endTimePath` | string | Yes | JSONPath to the request's end time. |
| `granularity` | object | Yes | A value source describing the time-bucket size. Only `DAY` is currently supported. |
| `dataDestinationPath` | string | Yes | JSONPath, relative to each item, where the per-date rows will be placed. |
| `keyName` | string | Yes | The name of the field that will hold each row's date. |

Below you can find a before/after example. The original response holds metric arrays indexed by day:

```
{
  "data": [
    {
      "id": "1647935464530235393",
      "id_data": [
        {
          "metrics": {
            "impressions": [
              0,
              327,
              55
            ],
            "app_clicks": [
              0,
              6,
              2
            ]
          }
        }
      ]
    }
  ],
  "request": {
    "params": {
      "start_time": "2023-03-31T21:00:00Z",
      "end_time": "2023-04-02T21:00:00Z",
      "granularity": "DAY"
    }
  }
}
```

After the adapter runs, each per-date entry becomes its own object inside `id_data`, with the date attached:

```
{
  "data": [
    {
      "id": "1647935464530235393",
      "id_data": [
        {
          "date": "2023-03-31",
          "impressions": 0,
          "app_clicks": 0
        },
        {
          "date": "2023-04-01",
          "impressions": 327,
          "app_clicks": 6
        },
        {
          "date": "2023-04-02",
          "impressions": 55,
          "app_clicks": 2
        }
      ]
    }
  ]
}
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.data.*.id_data.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "time_series",
        "config": {
          "dataPath": "$.data.*",
          "valuesPath": "$.id_data.0.metrics",
          "startTimePath": "$.request.params.start_time",
          "endTimePath": "$.request.params.end_time",
          "granularity": {
            "source": "jsonPath",
            "value": "$.request.params.granularity"
          },
          "dataDestinationPath": "$.id_data",
          "keyName": "date"
        }
      }
    ]
  }
}
```

Below you can find example field definitions that read from the transformed structure:

```
[
  {
    "id": "date",
    "label": "Date",
    "dataType": "string.time.date",
    "value": {
      "source": "jsonPath",
      "value": "$.date"
    }
  },
  {
    "id": "impressions",
    "label": "Impressions",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.impressions"
    }
  },
  {
    "id": "app_clicks",
    "label": "App clicks",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.app_clicks"
    }
  }
]
```

## Combining with flatten_values

With `time_series` alone, each row holds only the per-date fields — the parent's other fields (such as `id`) cannot be accessed easily on those rows. If your report needs fields from both the parent level (for example to know which campaign or entity each per-date row belongs to) and the per-date values, chain `time_series` with the [Flatten values](/docs/flatten-values.md) adapter so each per-date entry becomes its own row at `$.data.*` that also carries the parent's other fields. The per-date keys are prefixed with the source array's name (for example `id_data_date`, `id_data_impressions`).

After both adapters run, each per-date entry becomes its own row under `data`, with the parent's `id` preserved and the per-date metric keys prefixed with `id_data_`:

```
{
  "data": [
    {
      "id": "1647935464530235393",
      "id_data_date": "2023-03-31",
      "id_data_impressions": 0,
      "id_data_app_clicks": 0
    },
    {
      "id": "1647935464530235393",
      "id_data_date": "2023-04-01",
      "id_data_impressions": 327,
      "id_data_app_clicks": 6
    },
    {
      "id": "1647935464530235393",
      "id_data_date": "2023-04-02",
      "id_data_impressions": 55,
      "id_data_app_clicks": 2
    }
  ]
}
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.data.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "time_series",
        "config": {
          "dataPath": "$.data.*",
          "valuesPath": "$.id_data.0.metrics",
          "startTimePath": "$.request.params.start_time",
          "endTimePath": "$.request.params.end_time",
          "granularity": {
            "source": "jsonPath",
            "value": "$.request.params.granularity"
          },
          "dataDestinationPath": "$.id_data",
          "keyName": "date"
        }
      },
      {
        "type": "flatten_values",
        "config": {
          "dataPath": "$.data.*",
          "valuesPath": "$.id_data.*"
        }
      }
    ]
  }
}
```

Below you can find example field definitions that read from the transformed structure:

```
[
  {
    "id": "id",
    "label": "ID",
    "dataType": "string.text.value",
    "value": {
      "source": "jsonPath",
      "value": "$.id"
    }
  },
  {
    "id": "date",
    "label": "Date",
    "dataType": "string.time.date",
    "value": {
      "source": "jsonPath",
      "value": "$.id_data_date"
    }
  },
  {
    "id": "impressions",
    "label": "Impressions",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.id_data_impressions"
    }
  },
  {
    "id": "app_clicks",
    "label": "App clicks",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.id_data_app_clicks"
    }
  }
]
```