Structure de l'API Insights Meta Ads

L’API Marketing de Meta est une Graph API — chaque objet a un identifiant, et vous naviguez entre objets en traversant des edges. Comprendre la hiérarchie et le « edge » Insights est le fondement pour construire tout pipeline Meta Ads fiable.

La hiérarchie d’objets à cinq niveaux

La structure publicitaire de Meta comporte cinq niveaux :

Business Manager
└── Ad Account
    └── Campaign
        └── Ad Set
            └── Ad

Business Manager est le conteneur de plus haut niveau. Il regroupe les comptes publicitaires, pages, pixels, system users et permissions. La plupart des pipelines interagissent au niveau du compte publicitaire et en dessous, mais Business Manager est là où vous gérez l’authentification.

Ad Account est l’unité de facturation. Toutes les dépenses sont suivies à ce niveau. Un seul Business Manager peut avoir des dizaines de comptes publicitaires — chacun pour une marque, un marché ou un client différent. Si vous construisez un pipeline multi-comptes, vous devez connaître tous les identifiants de comptes à l’avance (l’API n’a pas d’endpoint « lister tous les comptes publicitaires » avec une large couverture).

Campaign contrôle l’objectif (notoriété, trafic, conversions, leads). Les budgets peuvent résider au niveau campagne (optimisation du budget de campagne) ou au niveau groupe d’annonces.

Ad Set contrôle le ciblage, le placement, le planning et le budget. C’est là que réside le ciblage d’audience : démographies, centres d’intérêt, audiences personnalisées, lookalikes.

Ad est le niveau créatif — l’image, la vidéo, le texte et l’appel à l’action réels montrés aux utilisateurs.

Vous pouvez extraire des Insights à n’importe quel niveau de cette hiérarchie en appelant le edge Insights sur l’identifiant d’objet correspondant.

L’API Insights

Le reporting de performance vient entièrement de l’API Insights. C’est techniquement un « edge » de l’API Marketing — vous l’appelez comme :

GET /{object-id}/insights

Où {object-id} est l’identifiant d’un business, compte publicitaire, campagne, groupe d’annonces ou annonce. La réponse contient les métriques pour cet objet et la plage de dates que vous spécifiez.

Paramètres clés

Les paramètres de requête les plus importants à comprendre :

params = {
    'fields': 'impressions,clicks,spend,actions,action_values',
    'date_preset': 'last_28d',          # ou utiliser time_range
    'time_increment': 1,                 # 1 = ventilation quotidienne
    'level': 'ad',                       # account|campaign|adset|ad
    'action_attribution_windows': ['7d_click', '1d_view'],  # obligatoire !
    'breakdowns': [],                    # optionnel : âge, genre, pays, etc.
}

Si vous ne passez pas action_attribution_windows, Meta utilise ses valeurs par défaut — qui peuvent ne pas correspondre à ce qu’Ads Manager affiche. Spécifiez toujours les fenêtres d’attribution explicitement. C’est la cause unique la plus courante de divergences entre les données de l’entrepôt et l’interface de la plateforme.

Le paramètre time_increment: 1 demande des ventilations quotidiennes. Sans lui, vous obtenez des totaux agrégés pour toute la plage de dates. Les données quotidiennes sont presque toujours ce que vous souhaitez pour un pipeline d’entrepôt.

Champs disponibles

L’endpoint Insights expose plus de 70 champs. Les principaux dont presque chaque pipeline a besoin :

Catégorie	Champs
Volume	`impressions`, `reach`, `frequency`
Engagement	`clicks`, `ctr`, `cpc`, `cpm`
Dépenses	`spend`
Vidéo	`video_thruplay_watched_actions`, `video_p25_watched_actions` à `video_p100_watched_actions`
Conversions	`actions`, `action_values`, `conversions`, `cost_per_action_type`

Les champs actions et action_values retournent des tableaux JSON imbriqués plutôt que des colonnes plates — c’est là que réside la complexité d’ingénierie principale. Voir Meta Ads Actions Array in BigQuery pour le traitement complet.

Restrictions sur les ventilations

Toutes les combinaisons de ventilations ne fonctionnent pas. Certaines retournent des erreurs API sans documentation claire sur lesquelles sont invalides. Les règles pratiques :

Les métriques d’action off-Meta (événements API Conversions, événements Pixel) ne peuvent pas utiliser les ventilations régionales, horaires ou plusieurs ventilations au niveau action
Les données avec ventilations ne sont conservées que 13 mois (vs 37 mois pour les données agrégées sans ventilations)
reach et frequency avec ventilations ne sont conservés que 6 mois
Les métriques uniques comme reach ne peuvent pas être sommées sur les ventilations — ce sont des comptages estimés et la sommation crée une inflation artificielle due au chevauchement des audiences

Ce dernier point importe pour la conception du stockage. Si vous demandez des données quotidiennes avec des ventilations par âge, le reach total sur tous les groupes d’âge dépassera le reach réel. Stockez ces métriques soigneusement et documentez leur nature non additive.

Versioning

Meta publie environ deux versions majeures d’API par an, chacune supportée pendant environ deux ans. À début 2026 :

v24.0 (actuelle, octobre 2025)
v22.0 (minimum supportée)
Tout ce qui est plus ancien que v22.0 : déprécié

Les API Advantage+ Shopping et App Campaign héritées sont entièrement dépréciées en mai 2026. Le calendrier de dépréciation est public, mais Meta ne vous avertit pas dans les réponses API — vous devez suivre vous-même les annonces de dépréciation.

L’implication opérationnelle : épinglez votre pipeline à une version spécifique et planifiez les mises à niveau au moins six mois avant la fin de vie. Une migration de version API non planifiée est une urgence ; une planifiée est une maintenance de routine. Le défi des changements de schéma sur toutes les plateformes est particulièrement aigu avec Meta en raison de la cadence trimestrielle.

Authentification

Options de token pour les pipelines en production :

Type de token	Expiration	Notes
Token utilisateur personnel	~60 jours	Expire silencieusement
Token utilisateur longue durée	~60 jours	Même comportement d’expiration
Token d’accès System User	Jamais	Recommandé pour la production

Les tokens personnels et longue durée expirent après environ 60 jours. Quand ils expirent, le pipeline s’arrête silencieusement — pas d’alerte, le token retourne simplement des erreurs d’authentification. Si vous ne surveillez pas spécifiquement les erreurs d’auth, vous découvrirez l’expiration quand quelqu’un demandera pourquoi les données se sont arrêtées.

Les tokens System User n’expirent pas. Créez-les dans Business Settings sous System Users :

Créez un System User (utilisez le rôle Admin)
Accordez l’accès aux comptes publicitaires spécifiques dont le pipeline a besoin
Générez le token avec ces permissions : ads_read, ads_management, business_management

La portée des permissions importe. ads_read est le minimum pour un accès pipeline en lecture seule. ads_management est nécessaire si votre pipeline écrit quoi que ce soit (la plupart ne le font pas). business_management est nécessaire pour les objets au niveau business.

Limites de débit

L’API Marketing a son propre système de limites de débit, séparé de l’API Graph standard. Deux niveaux :

Niveau d’accès	Points	Fenêtre de décroissance
Accès standard	60 points	300 secondes
Accès avancé	9 000 points	300 secondes

Les appels en lecture coûtent 1 point ; les appels en écriture coûtent 3.

Les limites Business Use Case évoluent avec la taille du compte. Pour ads_insights au niveau Accès Standard (niveau Accès Avancé) :

190 000 + (400 × active_ads) - (0,001 × user_errors) par heure

Le terme user_errors est important : les erreurs réduisent votre budget de limite de débit. Un pipeline défaillant qui martèle un endpoint défectueux aggrave le problème. Implémentez un circuit breaker qui pause l’extraction après des échecs consécutifs.

Surveillez trois en-têtes de réponse pour rester sous les limites :

X-Ad-Account-Usage
X-Business-Use-Case
X-FB-Ads-Insights-Throttle

Pour les grandes plages de dates, utilisez le reporting asynchrone (async=true) plutôt que les appels synchrones. L’API soumet un job de reporting et retourne un identifiant de job ; vous interrogez régulièrement pour savoir si c’est terminé. Associez cela à un backoff exponentiel sur les erreurs 429.

Pour l’Accès Avancé (limites de débit plus élevées), soumettez une demande d’App Review avec une démonstration screencast de votre cas d’usage. Faites-le tôt — le processus de révision prend du temps et vous voudrez les limites plus élevées avant d’en dépendre en production.

Construire vs acheter

Avec cette surface d’API, le calcul construire-ou-acheter pour l’extraction est réel. Les principales options :

Fivetran : gère versioning, limites de débit, fenêtres de lookback automatiquement ; commence à ~500 $/mois avec des packages dbt natifs
Airbyte : open-source ou cloud, lookback configurable ; l’Accès Avancé est plus difficile car vous partagez les credentials d’application d’Airbyte
dlt : source facebook_ads vérifiée avec évolution de schéma ; idéal pour les équipes Python-native
Python personnalisé : contrôle maximal, maintenance maximale ; vous gérez limites de débit, versioning, pagination, gestion des erreurs
BigQuery DTS : connecteur natif gratuit mais nécessite un token utilisateur actualisé tous les 60 jours — ce qui annule partiellement l’attrait de la solution managée

La fenêtre de lookback est la configuration critique indépendamment de l’outil. Les données d’attribution de Meta se mettent à jour rétroactivement pendant 3 à 7 jours. Un lookback de 28 jours est la valeur par défaut sûre. Voir Meta Ads Actions Array in BigQuery pour ce que cela signifie au niveau de la couche de transformation.