Metrics

Receive metrics by webhook via API

With POST /metrics/get-data-async you ask for the metrics and the API answers right away. The result arrives later in a POST to your metrics_webhook_url. It is the recommended path for long periods, and you need no OAuth, no app review and no token renewal.

The request

POST /api/metrics/get-data-async
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

{
  "metrics_webhook_url": "https://sua-aplicacao.com/webhooks/metricas",
  "customer_integration": "<connection uuid>",
  "start": "2026-08-01",
  "end": "2026-08-31",
  "metrics": [
    {
      "id": "f35a44ce-dac5-4188-aace-5c44a8952176",
      "reference_key": "ig:story_replies",
      "component": "number_v1",
      "metrics": [
        "replies"
      ]
    }
  ]
}

What you can do

  • Request several metrics from one connection in a single call, each with its own component.
  • Receive the result at an endpoint of yours, without keeping the request open while data is collected.
  • Use the same reference_keys from the GET /metrics/{integration_slug} catalog as the synchronous version.
  • Also request a comparison period with comparison_start and comparison_end.

Rules and limits

  • The immediate response is 200 with success: true and the message Metrics will be sent to your webhook.
  • The body delivered to the webhook is the metrics map at the root, without the data envelope of the synchronous version. Each key is the id (UUID) you sent.
  • metrics_webhook_url must be http or https and point to a public address: private IPs, loopback and link-local return 422.
  • Each call reads a single connection (customer_integration) and needs the x-customer-token of the customer that owns it.
  • On trial, start can go back at most 62 days and metrics accepts up to 15 items (trial_history_limit and trial_metrics_limit).

Main fields

FieldTypeRequiredDescription
metrics_webhook_urlstringYesPublic http or https URL that receives the metrics. Private IPs, loopback and link-local addresses are refused.
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).
metricsarrayYesThe requested metrics, at least one. Each item carries id, reference_key, component and metrics.
metrics.reference_keystringYesThe metric's identifier, from the GET /metrics/{integration_slug} catalog.

Who it is for

  • Batch monthly reports

    Your SaaS fires collection for every client overnight and processes each result as it lands on the webhook, with no threads stuck waiting.

  • Agency dashboards

    Ask for a whole year of an account when the panel loads and update the screen when the webhook delivers the data.

  • AI agents

    An agent requests the collection, moves on to other tasks and resumes the analysis when the webhook brings the metrics.

Frequently asked questions

What is the difference between get-data and get-data-async?

get-data keeps the request open and answers with the data inside a data object. get-data-async answers right away and delivers the metrics in a POST to your metrics_webhook_url, without the data envelope. For long periods, use the async one.

Can I point the webhook to localhost?

No. The URL is validated and must be public: private IPs, loopback and link-local are refused with 422. To test locally, use a tunnel with a public URL.

Can I collect from several accounts in one call?

No. Each call reads one connection, given in customer_integration. For several accounts, make one call per connection.

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.