ChatGPT Ads
Publicité ChatGPT

Insights et reporting dans l'API Ads

Idée centrale

L'API Ads expose quatre points de terminaison de reporting (« insights »), tous de même mécanique de requête et de forme de réponse, qui renvoient des métriques de performance (impressions, clics, dépense, CTR, CPC, CPM) agrégées par entité publicitaire (compte, campagne, groupe d'annonces, annonce) et par fenêtre temporelle, avec prise en charge du filtrage, du tri, de la segmentation et de la pagination par curseur.

Définition

Les quatre points de terminaison GET .../insights de la référence API Ads, qui permettent de récupérer par programmation les mêmes métriques de performance que celles consultées dans l'interface via Mesure des résultats dans Ads Manager.

Contexte

Cette page fait partie des huit pages de la référence API Ads. Elle s'appuie sur l'authentification et les conventions générales documentées dans Authentification, compte publicitaire et fichiers dans l'API Ads, et sur les entités documentées dans Campagnes et annonces dans l'API Ads (dont elle expose des sous-ensembles de métadonnées via fields[]/filters[]/sort[], sans redéfinir leurs schémas complets). Traitée comme une page à part du fait de son volume et de sa nature distincte (lecture agrégée de métriques, plutôt que gestion CRUD d'objets). Capturée le 2026-08-08.

Fonctionnement

Les quatre points de terminaison

L'endpoint choisi fixe la portée (« scope ») des résultats ; le paramètre aggregation_level choisit ensuite l'entité de ligne à l'intérieur de cette portée, selon la hiérarchie ad_account > campaign > ad_group > ad (un endpoint prend en charge son propre niveau et les niveaux inférieurs).

Terminologie de référence

TermeValeursSignification
{aggregation_level}ad_account, campaign, ad_group, adEntités de ligne publiques.
time_granularityhourly, daily, monthly, noneTaille des tranches temporelles. none renvoie une seule tranche pour toute la fenêtre.
segments[]product, country, deviceDimension de ventilation optionnelle supplémentaire (une seule à la fois).
{metric}impressions, clicks, spend, ctr, cpc, cpmChamps numériques agrégés.
{aggregation_level}.idex. campaign.idChamp d'identifiant canonique, valide quand ce niveau est présent dans la ligne.
{aggregation_level}.{metric}ex. campaign.impressions, ad.clicksMétrique pour l'entité de ligne.
{aggregation_level}.{metadata}ex. campaign.name, campaign.status, ad.review_status, ad_account.budget.lifetimeChamps de métadonnées canoniques.
{segment}.{metric}ex. product.impressions, country.clicksValide seulement si le segment correspondant est demandé.
{segment}.{metadata}ex. product.feed_id, product.title, country.name, device.typeValide seulement si le segment correspondant est demandé.
metadata.{field}metadata.readable_time, metadata.timezoneMétadonnées de rapport ; sérialisées en clés à plat (readable_time, timezone).
filters[].operatorIN, GREATER_THAN, LESS_THANIN pour l'égalité, les deux autres pour des seuils numériques.
sort[].directionasc, descOrdre de tri.
includes[]zero_impression_items, zero_impression_productsExpansions optionnelles de lignes à zéro métrique.
time_ranges[].typeunix_range, hour_range, date_rangeunix_range : start/end en secondes Unix. hour_range : since/until locaux YYYY-MM-DDTHH. date_range : since/until locaux YYYY-MM-DD, until inclusif.

Paramètres de requête (tous optionnels)

ParamètreTypeRègles
time_granularitystringPar défaut daily.
aggregation_levelstringFixe l'entité de ligne dans la portée de l'endpoint.
time_rangesstring[]Au moins une borne requise, dans les 5 dernières années, pas dans le futur.
fieldsstring[]Par défaut : impressions, plus readable_time en résultats tranchés, plus le nom par défaut de l'entité de ligne.
filtersstring[]Objets de filtre encodés en JSON.
sortstring[]Objets de tri encodés en JSON.
segmentsstring[]Au plus un segment.
override_segment_group_orderstring[]Réordonne les groupes de segmentation.
includesstring[]Au plus une valeur d'include.
limitinteger1 à 2000. Par défaut 20.
before / afterstringCurseurs de pagination (un seul à la fois).

Note explicite de la source : fields[] utilise des noms canoniques, mais de nombreux champs de réponse sont sérialisés en clés « à plat » — ex. campaign.id → campaign_id, metadata.readable_time → readable_time, product.feed_id → product_feed_id.

Filtres

filters[] : objets JSON {field, operator, value}, répétables (combinés en AND). field doit être un champ canonique valide pour la forme de ligne courante. operator : IN (égalité, value en tableau de chaînes) ou GREATER_THAN/LESS_THAN (seuils numériques, value en nombre). Exemple : {"field":"campaign.id","operator":"IN","value":["cmpn_101"]}.

Tris

sort[] : objets JSON {field, direction}, répétables. field une clé de tri canonique valide pour la forme de ligne courante. direction : asc ou desc.

Segments

Includes

IncludeFonctionne quandAjoute
zero_impression_itemsRegroupement par entité par défaut uniquement (pas de segments[]).Lignes d'entité à zéro impression sur la fenêtre.
zero_impression_productsReporting produit uniquement : compte activé, segments[]=product, override_segment_group_order[]=product en premier, filters[] limité aux champs produit/ID/métriques.Lignes de produits configurés à zéro impression.

Exemples

Regroupement par campagne, granularité quotidienne :

curl -sS -G "https://api.ads.openai.com/v1/ad_account/insights" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  --data-urlencode 'time_granularity=daily' \
  --data-urlencode 'aggregation_level=campaign' \
  --data-urlencode 'fields[]=metadata.readable_time' \
  --data-urlencode 'fields[]=campaign.id' \
  --data-urlencode 'fields[]=campaign.name' \
  --data-urlencode 'fields[]=campaign.clicks' \
  --data-urlencode 'fields[]=campaign.impressions' \
  --data-urlencode 'fields[]=campaign.spend' \
  --data-urlencode 'time_ranges[]={"type":"unix_range","start":1777075200,"end":1777248000}'

Réponse (extrait) : enveloppe object: "list", data[] avec pour chaque ligne id (composite, ex. start=...:end=...:entity_id=cmpn_101), start_time, end_time, readable_time, campaign_id, campaign_name, impressions, clicks, spend ; puis count, first_id, last_id, has_more.

Filtrage, tri et pagination : filters[]={"field":"campaign.id","operator":"IN","value":["cmpn_101"]}, sort[]={"field":"ad.clicks","direction":"desc"}, limit=1 — la réponse contient une seule ligne avec has_more: true, signe explicite qu'il existe d'autres lignes au-delà de la page renvoyée.

Segmentation produit avec expansion « zéro impression » — regroupement produit d'abord (override_segment_group_order[]=product puis ad_account) avec includes[]=zero_impression_products : les lignes synthétiques à zéro impression omettent les champs de métriques indisponibles de la réponse.

Éléments essentiels

Distinctions importantes

Ne pas confondre les noms de champs canoniques utilisés dans fields[]/filters[]/sort[] (ex. campaign.id) avec les clés « à plat » de la réponse JSON (ex. campaign_id) : la sérialisation change le nom du champ entre la requête et la réponse.

Ne pas confondre cette page (reporting programmatique via l'API REST) avec Mesure des résultats dans Ads Manager (mêmes métriques, mais consultées depuis l'interface Ads Manager : vue tableau, export CSV, graphiques) : deux angles complémentaires du même domaine fonctionnel.

Cas pratiques

Aucun cas pratique disponible : identifiants et valeurs de métriques (cmpn_101, ad_501, sku_1) manifestement fictifs et illustratifs.

Erreurs fréquentes

Ne pas demander segments[] sans définir override_segment_group_order[] en requête segmentée : l'ordre des groupes change la signification des métriques groupées.

Ne pas demander time_granularity=hourly en combinaison avec une segmentation : seules none, daily et monthly sont listées comme prises en charge en mode segmenté (voir « Limites et nuances »).

Ne pas interpréter une ligne synthétique à zéro impression comme une erreur de données : ces lignes omettent volontairement les champs de métriques indisponibles.

Limites et nuances

Relations

Points à vérifier

Sources