Metrics
Obtenir les données de graphiques de métriques via l'API
Le component définit le format du résultat. Avec chart_v1 dans POST /metrics/get-data, la métrique revient sous forme de données de graphique (ligne, secteurs, barres) que votre front-end affiche avec la bibliothèque de votre choix. Sans collecte ni agrégation par plateforme.
L'appel
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"
]
}
]
}Ce que vous pouvez faire
- Demander des métriques au format graphique avec le component chart_v1, avec number_v1 et des tableaux dans le même appel.
- Trouver quelles métriques sont des graphiques dans le catalogue GET /metrics/{integration_slug}, qui donne le component par défaut de chacune.
- Combiner un graphique avec une période de comparaison (comparison_start et comparison_end).
- Utiliser la version asynchrone (get-data-async) pour les graphiques sur de longues périodes.
Règles et limites
- Copiez l'élément du catalogue dans metrics[] : chaque élément de data est déjà un élément de requête valide.
- Le format du résultat dépend du component demandé ; le payload est ouvert, lisez donc le résultat de chaque métrique par sa clé id.
- Si une métrique échoue seule, elle revient sous forme d'objet d'erreur (invalid_metrics_combination, no_data_in_period, internal_error ou expired_token) et les autres arrivent avec le statut 200.
- Chaque appel lit une connexion (customer_integration) et exige le x-customer-token du client.
- En période d'essai, start remonte de 62 jours au maximum et metrics accepte jusqu'à 15 éléments.
Champs principaux
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| 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.reference_key | string | Oui | Métrique dont le catalogue indique chart_v1, comme ig:followers_gender. |
| metrics.component | string | Oui | Utilisez chart_v1 pour recevoir les données au format graphique. |
| metrics.metrics | array | Oui | Les valeurs demandées au sein de la métrique. Copiez-les depuis l'élément du catalogue. |
| metrics.id | string | Oui | UUID que vous générez ; c'est la clé du résultat dans la réponse. |
Pour qui
Panneaux de performance dans votre SaaS
Affichez l'évolution de la portée ou de la dépense en graphiques en ligne dans votre produit, avec les données du compte connecté du client.
Rapports d'agence
Construisez des pages de rapport avec des graphiques par plateforme sans intégrer l'API de chaque réseau social.
Agents IA avec contexte visuel
Un agent récupère la série de données d'un graphique et décrit la tendance à l'utilisateur.
Questions fréquentes
Comment savoir si une métrique vient en graphique ?
Dans le catalogue GET /metrics/{integration_slug}, chaque élément porte son component par défaut. Celles avec chart_v1 renvoient des données de graphique.
L'API dessine-t-elle le graphique ?
Non. Elle renvoie les données au format chart_v1 ; l'affichage revient à votre front-end.
Puis-je mélanger graphiques et nombres dans un appel ?
Oui. Chaque élément de metrics[] a son component, et chaque résultat revient sous l'id de l'élément.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
