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

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).
comparison_startstringNoStart of the comparison period (YYYY-MM-DD). Only considered if comparison_end is also sent.
comparison_endstringNoEnd of the comparison period (YYYY-MM-DD).
client_timezonestringNoTimezone identifier, such as America/Sao_Paulo (default).
metricsarrayYesThe 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.

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.