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

FieldTypeRequiredDescription
customer_integrationstringYesUUID of the customer's connection the metrics are read from. One per call.
startstringYesStart of the period (YYYY-MM-DD). Must be less than or equal to end.
endstringYesEnd of the period (YYYY-MM-DD).
metrics.reference_keystringYesA metric whose catalog entry is chart_v1, such as ig:followers_gender.
metrics.componentstringYesUse chart_v1 to get the data in chart format.
metrics.metricsarrayYesThe values requested within that metric. Copy them from the catalog item.
metrics.idstringYesA 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.

Related

See everything you can do with Metrics

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.