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

ChampTypeObligatoireDescription
customer_integrationstringOuiUUID de la connexion du client dont les métriques sont lues. Une par appel.
startstringOuiDébut de la période (YYYY-MM-DD). Doit être inférieur ou égal à end.
endstringOuiFin de la période (YYYY-MM-DD).
metrics.reference_keystringOuiMétrique dont le catalogue indique chart_v1, comme ig:followers_gender.
metrics.componentstringOuiUtilisez chart_v1 pour recevoir les données au format graphique.
metrics.metricsarrayOuiLes valeurs demandées au sein de la métrique. Copiez-les depuis l'élément du catalogue.
metrics.idstringOuiUUID 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.

Voir aussi

Voir tout ce que vous pouvez faire avec Metrics

Voyez Connect appliqué à votre produit.

Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.