--- title: "Time series adapter in Connector builder | Supermetrics" slug: "time-series" description: "Learn how the time series adapter in Connector builder 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" } } ] ```