Metrics
Compare metrics across periods via API
In POST /metrics/get-data you send the main period and, if you want, a comparison period. The response already carries the current and the previous value, so your product shows the change without a second call. No OAuth, no app review, no token renewal.
The request
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-08-01",
"end": "2026-08-31",
"comparison_start": "2026-07-01",
"comparison_end": "2026-07-31",
"metrics": [
{
"id": "f35a44ce-dac5-4188-aace-5c44a8952176",
"reference_key": "fb_ads:spend",
"component": "number_v1",
"metrics": [
"spend"
]
}
]
}What you can do
- Compare this month with the previous one, or any pair of periods, in one call.
- Request several metrics at once, each with its own component.
- Set the timezone with client_timezone so days close the way your customer expects.
- Use the async version (get-data-async) with the same comparison fields for long periods.
Rules and limits
- comparison_start is only considered if comparison_end is also sent.
- In the spec example, a number_v1 comes back with value (current period) and previous_value (comparison period).
- The result comes in the data object, keyed by each metric's id (UUID).
- If one metric fails on its own, it comes back as an error object (for example no_data_in_period) and the others come normally, with status 200.
- Each call reads one connection (customer_integration) and needs the customer's x-customer-token.
Main fields
| Field | Type | Required | Description |
|---|---|---|---|
| customer_integration | string | Yes | UUID of the customer's connection the metrics are read from. One per call. |
| start | string | Yes | Start of the period (YYYY-MM-DD). Must be less than or equal to end. |
| end | string | Yes | End of the period (YYYY-MM-DD). |
| comparison_start | string | No | Start of the comparison period (YYYY-MM-DD). Only considered if comparison_end is also sent. |
| comparison_end | string | No | End of the comparison period (YYYY-MM-DD). |
| client_timezone | string | No | Timezone identifier, such as America/Sao_Paulo (default). |
| metrics | array | Yes | The requested metrics, at least one. Each item carries id, reference_key, component and metrics. |
Who it is for
Change cards on dashboards
Your panel shows spend or followers with an up or down arrow against the previous period, from a single response.
Agency monthly reports
Generate the month-over-month comparison for each client without computing the difference on your side.
Agents that explain changes
An agent reads current and previous values and writes the analysis of what changed, with numbers coming from the API.
Frequently asked questions
How do I ask for the comparison?
Send comparison_start and comparison_end along with start and end in POST /metrics/get-data. If you send only one of the two, the comparison is not considered.
Does the comparison period need the same length?
The spec does not require it: you choose both dates. For a fair comparison, use periods of the same length.
Does it work with every metric?
It depends on the metric and the component. The spec example shows number_v1 coming back with value and previous_value. Try the metric you need from the GET /metrics/{integration_slug} catalog.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
