Metrics
Recevoir des métriques par webhook via l'API
Avec POST /metrics/get-data-async, vous demandez les métriques et l'API répond immédiatement. Le résultat arrive ensuite dans un POST vers votre metrics_webhook_url. C'est la voie recommandée pour les longues périodes, sans OAuth, sans revue d'app ni renouvellement de token.
L'appel
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"
]
}
]
}Ce que vous pouvez faire
- Demander plusieurs métriques d'une connexion en un seul appel, chacune avec son component.
- Recevoir le résultat sur un endpoint à vous, sans garder la requête ouverte pendant la collecte.
- Utiliser les mêmes reference_keys du catalogue GET /metrics/{integration_slug} que la version synchrone.
- Demander aussi une période de comparaison avec comparison_start et comparison_end.
Règles et limites
- La réponse immédiate est 200 avec success: true et le message Metrics will be sent to your webhook.
- Le corps livré au webhook est la table des métriques à la racine, sans l'enveloppe data de la version synchrone. Chaque clé est l'id (UUID) que vous avez envoyé.
- metrics_webhook_url doit être http ou https et pointer vers une adresse publique : IP privées, loopback et link-local renvoient 422.
- Chaque appel lit une seule connexion (customer_integration) et exige le x-customer-token du client qui en est propriétaire.
- En période d'essai, start peut remonter de 62 jours au maximum et metrics accepte jusqu'à 15 éléments (trial_history_limit et trial_metrics_limit).
Champs principaux
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| metrics_webhook_url | string | Oui | URL http ou https publique qui reçoit les métriques. Les IP privées, loopback et link-local sont refusées. |
| customer_integration | string | Oui | UUID de la connexion du client dont les métriques sont lues. Une par appel. |
| start | string | Oui | Début de la période (YYYY-MM-DD). Doit être inférieur ou égal à end. |
| end | string | Oui | Fin de la période (YYYY-MM-DD). |
| metrics | array | Oui | Liste des métriques demandées, au moins une. Chaque élément porte id, reference_key, component et metrics. |
| metrics.reference_key | string | Oui | Identifiant de la métrique, issu du catalogue GET /metrics/{integration_slug}. |
Pour qui
Rapports mensuels en lot
Votre SaaS lance la collecte de tous les clients la nuit et traite chaque résultat à son arrivée sur le webhook, sans threads bloqués.
Tableaux de bord d'agence
Demandez toute l'année d'un compte au chargement du panneau et mettez l'écran à jour quand le webhook livre les données.
Agents IA
Un agent demande la collecte, passe à d'autres tâches et reprend l'analyse quand le webhook apporte les métriques.
Questions fréquentes
Quelle différence entre get-data et get-data-async ?
get-data garde la requête ouverte et répond avec les données dans un objet data. get-data-async répond immédiatement et livre les métriques dans un POST vers votre metrics_webhook_url, sans l'enveloppe data. Pour les longues périodes, utilisez l'asynchrone.
Puis-je pointer le webhook vers localhost ?
Non. L'URL est validée et doit être publique : IP privées, loopback et link-local sont refusées avec 422. Pour tester en local, utilisez un tunnel avec une URL publique.
Puis-je collecter plusieurs comptes en un seul appel ?
Non. Chaque appel lit une connexion, indiquée dans customer_integration. Pour plusieurs comptes, faites un appel par connexion.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
