ChatGPT Ads : mesurer l’impact réel de vos annonces visuelles avec l’API Insights

1. Récupérer les données de base : ventes attribuées et dépenses

L’API Insights expose deux métriques clés pour calculer le ROAS :

• order_created_attributed_sales : valeur totale des ventes attribuées à vos annonces, exprimée dans la devise du compte.
• spend : montant dépensé pour la campagne, le groupe d’annonces ou l’annonce.

Ces données sont disponibles via quatre endpoints, selon le niveau d’agrégation souhaité :

• GET /v1/ad_account/insights : performance globale du compte.
• GET /v1/campaigns/{campaign_id}/insights : performance d’une campagne spécifique.
• GET /v1/ad_groups/{ad_group_id}/insights : performance d’un groupe d’annonces.
• GET /v1/ads/{ad_id}/insights : performance d’une annonce individuelle.

Exemple de requête pour une campagne

curl -G "https://api.ads.openai.com/v1/campaigns/cmpn_123/insights" \
  -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}" \
  --data-urlencode 'time_granularity=daily' \
  --data-urlencode 'time_ranges[]={"type":"date_range","since":"2026-10-01","until":"2026-10-07","timezone":"Europe/Paris"}' \
  --data-urlencode 'fields[]=spend' \
  --data-urlencode 'fields[]=order_created_attributed_sales' \
  --data-urlencode 'fields[]=order_created_roas'

La réponse inclut les métriques demandées pour chaque jour de la période :

{
  "data": [
    {
      "date": "2026-10-01",
      "spend": 125.50,
      "order_created_attributed_sales": 502.00,
      "order_created_roas": 4.00
    },
    {
      "date": "2026-10-02",
      "spend": 89.20,
      "order_created_attributed_sales": 267.60,
      "order_created_roas": 3.00
    }
  ]
}

À noter : Si order_created_roas retourne null, cela peut indiquer que les données de ventes sont manquantes ou que les dépenses sont à zéro (F8). Ce n’est pas une preuve d’inefficacité, mais un signal pour vérifier la configuration du suivi des conversions.

2. Calculer le ROAS et segmenter par visuel

Le ROAS est calculé automatiquement par l’API comme le ratio order_created_attributed_sales / spend. Une valeur de 4 signifie que chaque euro dépensé génère 4 € de ventes attribuées (F2).

2.1 Isoler l’impact des annonces visuelles

L’API ne segmente pas directement par type de créatif (ex: chat_card), mais vous pouvez :

1. Récupérer la liste des annonces avec leur creative.type via GET /v1/ads.
2. Filtrer les annonces de type chat_card (F5).
3. Interroger l’API Insights pour chaque ad_id identifié.

2.2 Segmenter par pays et appareil

Pour comparer les performances par pays ou appareil, ajoutez un segment à votre requête :

curl -G "https://api.ads.openai.com/v1/campaigns/cmpn_123/insights" \
  -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}" \
  --data-urlencode 'aggregation_level=campaign' \
  --data-urlencode 'segments[]=country' \
  --data-urlencode 'fields[]=country.name' \
  --data-urlencode 'fields[]=country.spend' \
  --data-urlencode 'fields[]=country.order_created_attributed_sales'

Cette requête retourne les dépenses et ventes attribuées pour chaque pays, ce qui permet d’identifier les marchés les plus performants (F3).

3. Affiner l’attribution avec les fenêtres de conversion

Les ventes attribuées incluent les conversions click-through (clics) et view-through (vues), avec des fenêtres par défaut de 30 jours pour les clics et 1 jour pour les vues (F4). Pour ajuster ces fenêtres :

• Utilisez l’endpoint POST /v1/conversions/insights avec les paramètres :
• attribution_window_days : 7, 14 ou 30 jours pour les clics.
• view_through_attribution_window_days : 0 (désactivé) ou 1 jour pour les vues.

Exemple de requête avec fenêtre personnalisée

curl -X POST "https://api.ads.openai.com/v1/conversions/insights" \
  -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_ids": ["cmpn_123"],
    "time_ranges": [{"type": "date_range", "since": "2026-10-01", "until": "2026-10-07"}],
    "attribution_window_days": 14,
    "view_through_attribution_window_days": 1,
    "include": ["order_created"]
  }'

Cette requête retourne les conversions et ventes attribuées avec une fenêtre de 14 jours pour les clics et 1 jour pour les vues, pouvant révéler des performances différentes pour les cycles d’achat longs (F4).

4. Automatiser le suivi avec un tableau de bord

Pour éviter les limites de pagination (2 000 lignes max par requête, F9), découpez les rapports par période ou entité. Voici un exemple de processus automatisé :

Étapes clés

1. Extraire les données quotidiennement : Utilisez un script Python ou un outil comme Make.com pour interroger l’API Insights et stocker les résultats dans une base de données (ex: PostgreSQL).
2. Calculer les métriques dérivées : Ajoutez des colonnes pour le ROAS, le CPA (coût par acquisition), ou le taux de conversion post-clic.
3. Visualiser les tendances : Utilisez un outil comme Metabase ou Tableau pour créer des graphiques montrant l’évolution du ROAS par campagne ou visuel.

Exemple de requête SQL pour un tableau de bord

SELECT
  date,
  campaign_id,
  SUM(spend) AS total_spend,
  SUM(order_created_attributed_sales) AS total_sales,
  SUM(order_created_attributed_sales) / NULLIF(SUM(spend), 0) AS roas,
  COUNT(DISTINCT ad_id) AS active_ads
FROM chatgpt_ads_insights
WHERE date BETWEEN '2026-10-01' AND '2026-10-07'
GROUP BY date, campaign_id
ORDER BY date;

Ce tableau de bord permet de suivre l’impact des ajustements (ex: changement de visuel, modification des fenêtres d’attribution) sur le ROAS.

5. Limites et bonnes pratiques

• Données manquantes : Les métriques comme le ROAS peuvent être nulles si les ventes attribuées ou les dépenses sont absentes (F8). Vérifiez la configuration du pixel de conversion ou de l’API Conversions pour assurer un suivi complet.
• Segmentation manuelle : L’API ne segmente pas automatiquement par type de créatif. Pour analyser les annonces visuelles, filtrez les ad_id des annonces chat_card (F5).
• Fenêtres d’attribution : Les fenêtres par défaut (30 jours pour les clics, 1 jour pour les vues) peuvent sous-estimer l’impact des campagnes avec des cycles d’achat longs. Ajustez-les via l’API Conversions (F4).
• Pagination : Pour les comptes avec un grand volume de données, découpez les rapports par période ou entité pour éviter l’erreur HTTP 413 (F9).

6. Prochaines étapes

Pour appliquer ces méthodes :

• Consultez notre guide sur le calcul du ROI des projets d’automatisation pour étendre ces principes à d’autres canaux.
• Explorez nos retours sur l’intégration des APIs publicitaires dans une stratégie IA plus large.
• Testez l’API Insights avec un compte de test pour valider les métriques avant de lancer des campagnes.