Qué lee la API

La API lee las mismas cifras que tus pantallas de Gloriads. Nunca cambia tu cuenta ni tus anuncios.

Endpoints

Cada parámetro y cada campo están en la referencia de la API, con un botón Try it.

Periodos

/summary, /timeline y /reports/products abarcan un periodo. Envía una de estas dos opciones:

• Si no envías nada: last_30_days, como el panel.
• Un range abarca días completos, los que suma el panel: last_30_days son los 30 días que terminan ayer, y this_month y this_year se detienen en ayer. Amazon atribuye una venta a su clic días después, así que hoy nunca está completo.
• today es hoy, y también lo es this_month el día 1 (todavía no tiene ningún día completo).
• all_time empieza en el día más antiguo que guarda Gloriads y llega hasta hoy, como Todo el historial en el panel.
• Para incluir hoy, envía start_date y end_date con end_date = hoy.
• timezone (Europe/Paris, America/New_York…) decide qué día es “hoy”. UTC por defecto.
• Cada respuesta repite en period los días que abarca.

Comparar dos periodos

Añade compare a /summary, /timeline o /reports/products, como Comparar con en el panel:

La respuesta añade un comparison con las cifras del periodo comparado y, para la inversión, las ventas, el ACOS, las impresiones, los clics, el CPC y las compras, cómo ha variado cada una:

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

• Los dos periodos terminan ayer, como en el panel: si las fechas llegan hasta hoy, se quita el día de hoy, y period lo indica.
• kind: "new" significa que la cifra era cero antes; kind: "none" significa que no hay nada que comparar (un ACOS sin ventas).
• tone indica si es una buena noticia, como los colores del panel. La inversión siempre es neutral.
• all_time no tiene nada antes, y today no tiene ningún día completo: comparison indica entonces el motivo en unavailable.
• Cuando Gloriads no guarda historial del periodo comparado, sus cifras son null y history_covered es false.

Filtros

Un valor desconocido se rechaza con un 400 que lo nombra: nunca se responde con ceros.

Totales de un periodo

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 y conversion_rate son porcentajes: 28.22 significa 28,22 %.
• purchases cuenta pedidos, no unidades, como Compras en la consola de Amazon Ads.
• Una cifra que no tiene base (un ACOS sin ventas) es null, nunca 0.

Día a día o mes a mes

/timeline acepta el mismo periodo y los mismos filtros, y devuelve en data un punto por día o por mes.

• granularity=auto (por defecto) elige días hasta 92 días y meses a partir de ahí, como el gráfico del panel.
• granularity=day se rechaza en un periodo de más de 92 días.
• Un día sin ninguna cifra no aparece.

Por producto

/reports/products devuelve una fila por producto anunciado (ASIN), en el orden que fijan sort (spend por defecto) y order (desc por defecto).

• product_id: null reúne lo que Amazon no vincula a ningún producto, sobre todo Sponsored Brands.
• title es el nombre del producto tal como lo da el informe de productos de Amazon, en el marketplace donde más gastó en el periodo. Vale null con product_id: null, y mientras Gloriads no haya recibido de Amazon los títulos de los productos de la cuenta.
• Las filas llegan por páginas: consulta Límites y errores.

TV por streaming

Los demás informes dejan fuera la TV por streaming (anuncios de TV en Prime Video y en aplicaciones de streaming), como el panel: Amazon no la incluye en el informe del que salen. /reports/streaming-tv la lee de un informe aparte de Amazon, para un solo marketplace.

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

• Un periodo de 31 días como máximo, dentro de los últimos 95 días: son los límites de Amazon para este informe.
• La primera llamada para un periodo puede responder "status": "pending" mientras Amazon genera el informe, normalmente unos minutos. Vuelve a llamar pasados los segundos que indica meta.retry_after_seconds. A partir de ahí, el informe se conserva 3 horas.
• Cada campaña llega con su inversión, sus impresiones, cpm (costo por 1000 impresiones), sus clics, sus ventas, sus compras y units_sold.
• Los importes están en la moneda del propio marketplace, no en USD.
• "status": "unavailable": Amazon no ofrece TV por streaming a esta cuenta, por ejemplo a la de un autor de KDP.

Campañas y grupos de anuncios

Ambos necesitan marketplace_id: un id de /marketplaces.

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

• Listan las campañas activas y en pausa de Sponsored Products, Sponsored Brands y Display. Las campañas archivadas nunca aparecen.
• Los presupuestos y las pujas están en la moneda del propio marketplace (currency_code en /marketplaces).
• provenance indica si Gloriads creó la campaña, la cambió o nunca la tocó.
• /ad-groups?campaign_id=… conserva solo los grupos de anuncios de una campaña.
• Hasta 1000 filas por página (100 por defecto).

Palabras clave, segmentos y anuncios

/targets y /ads listan lo que hay dentro de una campaña. Ambos necesitan marketplace_id y campaign_id; ad_group_id conserva solo uno de sus grupos de anuncios.

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

• /targets lista cada palabra clave con su match_type (EXACT, PHRASE, BROAD), los segmentos de producto (ASIN), las categorías, los grupos de segmentación automática y la segmentación negativa, con su bid y su estado. bid: null significa que usa la puja predeterminada del grupo de anuncios.
• /ads lista cada anuncio con los productos que anuncia (product_ids).
• Se leen de Amazon en el momento en que lo pides, y no llevan cifras.
• Sponsored Products, Sponsored Brands y Display. Los archivados nunca aparecen.
• Hasta 1000 filas por página (100 por defecto).

Reglas y actividad

• /rules lista todas las reglas, empezando por la editada más recientemente.
• /rules/{rule_id}/runs muestra qué revisó y qué cambió cada ejecución reciente. Las pruebas no aparecen.
• /activity lista cada operación que Gloriads ejecutó en Amazon: una campaña creada o copiada, productos añadidos, los cambios de una regla, un cambio deshecho. Una ejecución de regla aparece una vez por marketplace, con el mismo rule_run_id. tool=rule conserva solo las de las reglas.
• /activity/{operation_id} lee una operación: consúltalo cada cierto tiempo para seguir una que todavía está en curso.
• /activity/{operation_id}/lines lista lo que hizo la operación, línea por línea: la campaña, el grupo de anuncios, el anuncio o el segmento, si se creó, se cambió o se archivó, cada valor antes y después, y el error de Amazon cuando una línea falló. Hasta 500 líneas por página: la ejecución de una regla puede tener 5000.

Actualización de las cifras

• Son las cifras de tu panel, leídas de los mismos datos con el mismo código.
• Los importes de rendimiento están en USD. Amazon convierte las cifras de cada marketplace.
• Amazon atribuye las ventas varios días después del clic, así que los últimos días de un periodo siguen creciendo durante un tiempo. meta.data_last_date indica hasta qué día llegan las cifras.
• Las campañas se leen de Amazon como mucho cada 30 minutos por marketplace. meta.synced_at indica cuándo. En la primera llamada para un marketplace, la lista puede llegar vacía con meta.syncing: true: vuelve a llamar un minuto después.
• Las cifras de los productos se actualizan una vez al día. Un periodo que empieza antes del historial que guarda Gloriads devuelve meta.history_covered: false.
• Las palabras clave, los segmentos y los anuncios se leen de Amazon en directo, en cada llamada: meta.read_at indica cuándo.
• Las cifras de TV por streaming se conservan 3 horas después de que Amazon genere su informe: meta.report_ready_at indica cuándo.