Metrics
Get chart data for metrics via API
The component sets the result format. With chart_v1 in POST /metrics/get-data, the metric comes back as chart data (line, pie, bar) that your front end renders with any library you like. No collecting and aggregating per platform.
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",
"metrics": [
{
"id": "f35a44ce-dac5-4188-aace-5c44a8952176",
"reference_key": "ig:followers_gender",
"component": "chart_v1",
"metrics": [
"followers"
],
"dimensions": [
"gender"
]
}
]
}What you can do
- Request metrics in chart format with component chart_v1, next to number_v1 and tables in the same call.
- Find which metrics are charts in the GET /metrics/{integration_slug} catalog, which gives each one's default component.
- Combine a chart with a comparison period (comparison_start and comparison_end).
- Use the async version (get-data-async) for charts over long periods.
Rules and limits
- Copy the catalog item into metrics[]: each item in data is already a valid request item.
- The result format depends on the requested component; the payload is open, so read each metric's result by its id key.
- If one metric fails on its own, it comes back as an error object (invalid_metrics_combination, no_data_in_period, internal_error or expired_token) and the others come with status 200.
- Each call reads one connection (customer_integration) and needs the customer's x-customer-token.
- On trial, start can go back at most 62 days and metrics accepts up to 15 items.
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). |
| metrics.reference_key | string | Yes | A metric whose catalog entry is chart_v1, such as ig:followers_gender. |
| metrics.component | string | Yes | Use chart_v1 to get the data in chart format. |
| metrics.metrics | array | Yes | The values requested within that metric. Copy them from the catalog item. |
| metrics.id | string | Yes | A UUID you generate; it is the key of the result in the response. |
Who it is for
Performance panels in your SaaS
Show reach or spend trends as line charts inside your product, with data from the customer's connected account.
Agency reports
Build report pages with charts per platform without integrating each social network API.
AI agents with visual context
An agent fetches a chart's data series and describes the trend to the user.
Frequently asked questions
How do I know if a metric comes as a chart?
In the GET /metrics/{integration_slug} catalog, each item carries its default component. Those with chart_v1 return chart data.
Does the API draw the chart?
No. It returns the data in the chart_v1 format; rendering is up to your front end.
Can I mix charts and numbers in one call?
Yes. Each item in metrics[] has its own component, and each result comes back under the item's id.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
