Metrics
Obtenir des métriques en tableaux et grilles via l'API
Avec le component datatable_v1 dans POST /metrics/get-data, la métrique revient sous forme de données tabulaires, avec des colonnes (metrics) et une ventilation par dimension. Il existe aussi datagrid_v1 pour les grilles, comme les stories Instagram. Une seule API pour tous les comptes connectés, sans intégration réseau par réseau.
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": "80e06171-759e-472e-9cff-25ae8e91e1e0",
"reference_key": "fb_ads:insights_by_campaign",
"component": "datatable_v1",
"metrics": [
"results",
"cost_per_results",
"spend",
"reach",
"impressions",
"ctr",
"cpc",
"cpm",
"frequency"
]
}
]
}Ce que vous pouvez faire
- Lister les campagnes Meta Ads avec résultats, coût par résultat, dépense, portée, impressions, CTR, CPC, CPM et fréquence avec fb_ads:insights_by_campaign.
- Choisir les colonnes dans metrics et la ventilation dans dimensions, avec les valeurs du catalogue GET /metrics/{integration_slug}.
- Demander des tableaux avec des nombres et des graphiques dans le même appel.
- Utiliser datagrid_v1 pour les grilles, comme les stories Instagram.
Règles et limites
- Copiez l'élément du catalogue dans metrics[] et remplacez metrics et dimensions par des clés de meta.setup du catalogue pour un autre découpage.
- Les éléments du catalogue portent déjà metrics et dimensions au format accepté : copiez-les tels quels.
- Le résultat arrive dans data, sous l'id (UUID) de chaque métrique, au format du component.
- Si une métrique échoue seule, elle revient sous forme d'objet d'erreur et les autres arrivent avec le statut 200.
- Chaque appel lit une connexion (customer_integration) et exige le x-customer-token du client.
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 du catalogue dont le component est datatable_v1 ou datagrid_v1, comme fb_ads:insights_by_campaign. |
| metrics.component | string | Oui | datatable_v1 pour des données tabulaires ; datagrid_v1 pour des grilles, comme les stories Instagram. |
| metrics.metrics | array | Oui | Les colonnes demandées (par exemple spend, reach, ctr). |
| metrics.dimensions | array | Non | La ventilation du résultat. Copiez-la depuis l'élément du catalogue. |
Pour qui
Tableau de campagnes dans votre produit
Listez les campagnes du client avec dépense, portée et CTR dans votre interface, sans intégrer Meta Ads.
Rapports de performance média payant
Construisez le classement des campagnes de chaque client pour le rapport mensuel de l'agence.
Agents qui analysent les campagnes
Un agent lit le tableau et signale les campagnes au pire coût par résultat.
Questions fréquentes
Quelle différence entre datatable_v1 et datagrid_v1 ?
datatable_v1 livre des données tabulaires ; datagrid_v1 livre une grille, comme celle des stories Instagram. Le catalogue de chaque plateforme indique le component de chaque métrique.
Comment ventiler le résultat par campagne ?
Utilisez fb_ads:insights_by_campaign, l'élément du catalogue Meta Ads qui porte déjà la dimension de campagne, et copiez ses metrics et dimensions.
Puis-je paginer le tableau ?
La spec ne décrit ni pagination ni tri pour les tableaux, ce n'est donc pas documenté ici. Le découpage se fait par la période, les métriques et les dimensions.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
