Ce que lit l'API

L'API lit les mêmes chiffres que vos écrans Gloriads. Elle ne modifie jamais votre compte ni vos publicités.

Endpoints

Chaque paramètre et chaque champ figurent dans la référence de l'API, avec un bouton Try it.

Périodes

/summary, /timeline et /reports/products couvrent une période. Envoyez l'un des deux :

• Sans paramètre : last_30_days, comme sur le tableau de bord.
• Un range couvre des jours complets, ceux qu'additionne le tableau de bord : last_30_days correspond aux 30 jours qui se terminent hier, et this_month comme this_year s'arrêtent à hier. Amazon attribue une vente à son clic plusieurs jours plus tard : aujourd'hui n'est donc jamais complet.
• today correspond à aujourd'hui, tout comme this_month le 1er du mois (il n'a encore aucun jour complet).
• all_time part du plus ancien jour que Gloriads conserve et va jusqu'à aujourd'hui, comme Depuis le début sur le tableau de bord.
• Pour inclure aujourd'hui, envoyez start_date et end_date, avec end_date = aujourd'hui.
• timezone (Europe/Paris, America/New_York…) détermine quel jour est « aujourd'hui ». UTC par défaut.
• Chaque réponse rappelle dans period les jours qu'elle couvre.

Comparer deux périodes

Ajoutez compare à /summary, /timeline ou /reports/products, comme Comparer à sur le tableau de bord :

La réponse ajoute comparison, avec les chiffres de la période comparée et, pour les dépenses, les ventes, l'ACOS, les impressions, les clics, le CPC et les achats, l'évolution de chacun :

"changes": {
  "spend": { "kind": "change", "percent": 18.2, "direction": "up", "tone": "neutral" },
  "acos": { "kind": "change", "percent": -6.5, "direction": "down", "tone": "good" }
}

• Les deux périodes s'arrêtent hier, comme sur le tableau de bord : si vos dates vont jusqu'à aujourd'hui, aujourd'hui en est retiré, et period l'indique.
• kind: "new" signifie que le chiffre était à zéro auparavant ; kind: "none", qu'il n'y a rien à comparer (un ACOS sans ventes).
• tone indique s'il s'agit d'une bonne nouvelle, comme les couleurs du tableau de bord. Les dépenses sont toujours neutral.
• all_time n'a rien avant lui, et today n'a aucun jour complet : comparison en donne alors la raison dans unavailable.
• Quand Gloriads ne conserve aucun historique pour la période comparée, ses chiffres valent null et history_covered vaut false.

Filtres

Une valeur inconnue est refusée par un 400 qui la nomme : l'API ne répond jamais par des zéros.

Totaux d'une période

curl "https://gloriads.com/api/v1/summary?range=last_month&marketplaces=US" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "period": { "start_date": "2026-09-01", "end_date": "2026-09-30", "range": "last_month", "timezone": "UTC" },
  "currency": "USD",
  "spend": 13140.53,
  "sales": 46562.2,
  "acos": 28.22,
  "roas": 3.54,
  "impressions": 3945723,
  "clicks": 13973,
  "ctr": 0.35,
  "average_cpc": 0.94,
  "purchases": 1479,
  "conversion_rate": 10.58,
  "by_marketplace": [ … ],
  "by_ad_product": [ … ],
  "meta": { "data_last_date": "2026-10-09", "history_covered": true, "truncated": false }
}

• acos, ctr et conversion_rate sont des pourcentages : 28.22 signifie 28,22 %.
• purchases compte les commandes, comme Achats dans la console, pas les unités.
• Un ratio sans base (un ACOS sans vente) vaut null, jamais 0.

Jour par jour ou mois par mois

/timeline prend la même période et les mêmes filtres, et renvoie dans data un point par jour ou par mois.

• granularity=auto (par défaut) choisit les jours jusqu'à 92 jours, les mois au-delà, comme le graphique du tableau de bord.
• granularity=day est refusé sur une période de plus de 92 jours.
• Un jour sans aucun chiffre est omis.

Par produit

/reports/products renvoie une ligne par produit promu (ASIN). Les lignes sont triées selon sort (spend par défaut) et order (desc par défaut).

• product_id: null regroupe ce qu'Amazon ne rattache à aucun produit, surtout Sponsored Brands.
• title est le nom du produit tel que le donne le rapport produits d'Amazon, sur la marketplace où il a le plus dépensé sur la période. Il vaut null pour product_id: null, et tant que Gloriads n'a pas reçu d'Amazon les titres des produits du compte.
• Les lignes arrivent par pages : voir Limites et erreurs.

Streaming TV

Comme le tableau de bord, les autres rapports n'incluent pas Streaming TV (les publicités TV sur Prime Video et les applications de streaming) : Amazon ne place pas ces campagnes dans le rapport dont ils proviennent. /reports/streaming-tv les lit dans un rapport Amazon distinct, pour une seule marketplace.

curl "https://gloriads.com/api/v1/reports/streaming-tv?marketplace_id=3478512345678901&range=last_30_days" \
  -H "Authorization: Bearer YOUR_API_KEY"

• Une période de 31 jours au plus, comprise dans les 95 derniers jours : ce sont les limites d'Amazon pour ce rapport.
• Le premier appel pour une période peut répondre "status": "pending" le temps qu'Amazon produise le rapport, en général quelques minutes. Rappelez après meta.retry_after_seconds. Le rapport est ensuite conservé 3 heures.
• Chaque campagne arrive avec ses dépenses, ses impressions, son cpm (coût pour 1 000 impressions), ses clics, ses ventes, ses achats et ses units_sold.
• Les montants sont dans la devise de la marketplace, pas en USD.
• "status": "unavailable" : Amazon ne propose pas Streaming TV à ce compte, par exemple celui d'un auteur KDP.

Campagnes et groupes de publicités

Les deux exigent marketplace_id : un id renvoyé par /marketplaces.

curl "https://gloriads.com/api/v1/campaigns?marketplace_id=3478512345678901&states=ENABLED" \
  -H "Authorization: Bearer YOUR_API_KEY"

• Ils listent les campagnes Sponsored Products, Sponsored Brands et Display activées et en pause. Les campagnes archivées ne sont jamais listées.
• Budgets et enchères sont dans la devise de la marketplace (currency_code dans /marketplaces).
• provenance indique si Gloriads a créé la campagne, l'a modifiée ou n'y a jamais touché.
• /ad-groups?campaign_id=… ne garde que les groupes de publicités d'une campagne.
• Jusqu'à 1 000 lignes par page (100 par défaut).

Mots-clés, cibles et publicités

/targets et /ads listent ce qui se trouve dans une campagne. Les deux exigent marketplace_id et campaign_id ; ad_group_id ne garde que l'un de ses groupes de publicités.

curl "https://gloriads.com/api/v1/targets?marketplace_id=3478512345678901&campaign_id=28430987654321" \
  -H "Authorization: Bearer YOUR_API_KEY"

• /targets liste chaque mot-clé avec son match_type (EXACT, PHRASE, BROAD), les ASIN ciblés, les catégories, les groupes de ciblage automatique et les ciblages négatifs, avec leur bid et leur état. bid: null signifie que l'enchère par défaut du groupe de publicités s'applique.
• /ads liste chaque publicité avec les produits qu'elle promeut (product_ids).
• Les deux lisent Amazon au moment où vous les appelez, et ne renvoient aucun chiffre.
• Sponsored Products, Sponsored Brands et Display. Les éléments archivés ne sont jamais listés.
• Jusqu'à 1 000 lignes par page (100 par défaut).

Règles et activité

• /rules liste toutes vos règles, les dernières modifiées en premier.
• /rules/{rule_id}/runs montre ce que chaque exécution récente a examiné et modifié. Les tests n'y figurent pas.
• /activity liste chaque opération que Gloriads a exécutée sur Amazon : une campagne créée ou copiée, des produits ajoutés, les modifications d'une règle, une annulation. L'exécution d'une règle apparaît une fois par marketplace, avec le même rule_run_id. tool=rule ne garde que celles des règles.
• /activity/{operation_id} lit une seule opération : appelez-le régulièrement pour suivre une opération encore en cours.
• /activity/{operation_id}/lines liste ce que l'opération a fait, ligne par ligne : l'élément concerné (campagne, groupe de publicités, publicité ou cible), s'il a été créé, modifié ou archivé, chaque valeur avant et après, et l'erreur renvoyée par Amazon quand une ligne a échoué. Jusqu'à 500 lignes par page : l'exécution d'une règle peut en compter 5 000.

Fraîcheur des chiffres

• Ce sont les chiffres de votre tableau de bord, lus dans les mêmes données avec le même code.
• Les montants des performances sont en USD. Amazon convertit les chiffres de chaque marketplace.
• Amazon attribue les ventes plusieurs jours après le clic : les derniers jours d'une période continuent donc d'augmenter pendant un moment. meta.data_last_date indique jusqu'à quel jour vont les chiffres.
• Les campagnes sont lues chez Amazon au plus toutes les 30 minutes par marketplace. meta.synced_at indique quand. Au tout premier appel pour une marketplace, la liste peut être vide avec meta.syncing: true : rappelez une minute plus tard.
• Les chiffres des produits sont actualisés une fois par jour. Une période qui commence avant l'historique que conserve Gloriads renvoie meta.history_covered: false.
• Les mots-clés, les cibles et les publicités sont lus en direct chez Amazon, à chaque appel : meta.read_at indique quand.
• Les chiffres Streaming TV sont conservés 3 heures après qu'Amazon a produit leur rapport : meta.report_ready_at indique quand.