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
| Field | Type | Required | Description |
|---|---|---|---|
| metrics_webhook_url | string | Yes | Public http or https URL that receives the metrics. Private IPs, loopback and link-local addresses are refused. |
| 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 | array | Yes | The requested metrics, at least one. Each item carries id, reference_key, component and metrics. |
| metrics.reference_key | string | Yes | The 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.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
