O que a API lê

A API lê os mesmos números das suas telas do Gloriads. Ela nunca altera a sua conta nem os seus anúncios.

Endpoints

Todos os parâmetros e todos os campos estão na referência da API, com um botão Try it.

Períodos

/summary, /timeline e /reports/products cobrem um período. Envie um destes:

• Nada enviado: last_30_days, como no painel.
• Um range cobre dias completos, os que o painel soma: last_30_days são os 30 dias que terminam ontem, e this_month e this_year param em ontem. A Amazon atribui uma venda ao clique alguns dias depois, então o dia de hoje nunca está completo.
• today é hoje, e this_month também, no dia 1º (ele ainda não tem nenhum dia completo).
• all_time começa no dia mais antigo que o Gloriads guarda e vai até hoje, como Todo o período no painel.
• Para incluir hoje, envie start_date e end_date, com end_date = hoje.
• timezone (Europe/Paris, America/New_York…) decide que dia é “hoje”. UTC por padrão.
• Toda resposta repete em period os dias que ela cobre.

Comparar dois períodos

Adicione compare a /summary, /timeline ou /reports/products, como Comparar com no painel:

A resposta acrescenta um comparison com os números do período comparado e, para gasto, vendas, ACOS, impressões, cliques, CPC e compras, a variação de cada um:

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

• Os dois períodos terminam ontem, como no painel: datas que chegam até hoje perdem o dia de hoje, e period indica isso.
• kind: "new" significa que o número era zero antes; kind: "none" significa que não há nada a comparar (ACOS sem vendas).
• tone diz se é uma boa notícia, como as cores do painel. O gasto é sempre neutral.
• all_time não tem nada antes dele, e today não tem nenhum dia completo: comparison então explica o motivo em unavailable.
• Quando o Gloriads não tem histórico do período comparado, os números dele são null e history_covered é false.

Filtros

Um valor desconhecido é recusado com um 400 que diz qual é, e nunca recebe zeros como resposta.

Totais de um período

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 e conversion_rate são porcentagens: 28.22 significa 28,22%.
• purchases conta pedidos, como Compras no console, não unidades.
• Um percentual sem base de cálculo é null, nunca 0: por exemplo, o ACOS (custo de publicidade das vendas) sem nenhuma venda.

Dia a dia ou mês a mês

/timeline aceita o mesmo período e os mesmos filtros, e retorna em data um ponto por dia ou por mês.

• granularity=auto (o padrão) escolhe dias até 92 dias e meses acima disso, como o gráfico do painel.
• granularity=day é recusado em um período de mais de 92 dias.
• Um dia sem nenhum número fica de fora.

Por produto

/reports/products retorna uma linha por produto anunciado (ASIN), ordenada por sort (spend por padrão) e order (desc por padrão).

• product_id: null reúne o que a Amazon não associa a nenhum produto, principalmente Sponsored Brands.
• title é o nome do produto como o relatório de produtos da Amazon o informa, no marketplace onde ele mais gastou no período. Vale null com product_id: null, e enquanto a Gloriads não tiver recebido da Amazon os títulos dos produtos da conta.
• As linhas vêm em páginas: veja Limites e erros.

Streaming TV

Os outros relatórios deixam de fora as campanhas de Streaming TV (anúncios de TV no Prime Video e em aplicativos de streaming), como o painel: a Amazon não as inclui no relatório de onde eles vêm. /reports/streaming-tv as lê em um relatório separado da Amazon, para um marketplace.

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

• Um período de 31 dias no máximo, dentro dos últimos 95 dias: os limites da Amazon para este relatório.
• A primeira chamada para um período pode responder "status": "pending" enquanto a Amazon gera o relatório, geralmente alguns minutos. Chame de novo depois de meta.retry_after_seconds. O relatório fica então guardado por 3 horas.
• Cada campanha vem com o seu gasto, impressões, cpm (custo por 1.000 impressões), cliques, vendas, compras e units_sold.
• Os valores estão na moeda do próprio marketplace, não em USD.
• "status": "unavailable": a Amazon não oferece Streaming TV para esta conta, por exemplo a de um autor do KDP.

Campanhas e grupos de anúncios

Os dois precisam de marketplace_id: um id de /marketplaces.

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

• Eles listam as campanhas ativas e pausadas de Sponsored Products, Sponsored Brands e Display. As arquivadas nunca aparecem.
• Orçamentos e lances ficam na moeda do próprio marketplace (currency_code em /marketplaces).
• provenance diz se o Gloriads criou a campanha, se a alterou ou se nunca mexeu nela.
• /ad-groups?campaign_id=… mantém apenas os grupos de anúncios de uma campanha.
• Até 1.000 linhas por página (100 por padrão).

Palavras-chave, segmentações e anúncios

/targets e /ads listam o que está dentro de uma campanha. Os dois precisam de marketplace_id e campaign_id; ad_group_id mantém apenas um dos grupos de anúncios dela.

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

• /targets lista cada palavra-chave com o seu match_type (EXACT, PHRASE, BROAD), as segmentações por produto (ASINs), as categorias, os grupos de segmentação automática e as negativas, com o bid e o status de cada uma. bid: null significa que ela usa o lance padrão do grupo de anúncios.
• /ads lista cada anúncio com os produtos que ele anuncia (product_ids).
• Eles são lidos na Amazon no momento em que você pede, e não trazem nenhum número.
• Sponsored Products, Sponsored Brands e Display. Os arquivados nunca aparecem.
• Até 1.000 linhas por página (100 por padrão).

Regras e atividade

• /rules lista todas as regras, da editada mais recentemente à mais antiga.
• /rules/{rule_id}/runs mostra o que cada execução recente analisou e alterou. Os testes não aparecem.
• /activity lista cada operação que o Gloriads executou na Amazon: uma campanha criada ou copiada, produtos adicionados, as alterações de uma regra, uma alteração desfeita. A execução de uma regra aparece uma vez por marketplace, com o mesmo rule_run_id. tool=rule mantém apenas as das regras.
• /activity/{operation_id} lê uma operação: chame-o em intervalos para acompanhar uma que ainda está em andamento.
• /activity/{operation_id}/lines lista o que a operação fez, linha por linha: a campanha, o grupo de anúncios, o anúncio ou a segmentação, se foi criado, alterado ou arquivado, cada valor antes e depois, e o erro da Amazon quando uma linha falhou. Até 500 linhas por página: a execução de uma regra pode ter 5.000.

Quão atualizados estão os números

• São os números do seu painel, lidos dos mesmos dados com o mesmo código.
• Os valores de desempenho estão em dólares americanos (USD). A Amazon converte os números de cada marketplace.
• A Amazon atribui as vendas vários dias depois do clique, então os últimos dias de um período ainda crescem por um tempo. meta.data_last_date diz até que dia vão os números.
• O Gloriads lê as campanhas na Amazon no máximo a cada 30 minutos, por marketplace. meta.synced_at diz quando. Na primeira chamada de um marketplace, a lista pode vir vazia com meta.syncing: true: chame de novo um minuto depois.
• Os números por produto são atualizados uma vez por dia. Um período que começa antes do histórico que o Gloriads guarda retorna meta.history_covered: false.
• Palavras-chave, segmentações e anúncios são lidos em tempo real na Amazon, a cada chamada: meta.read_at diz quando.
• Os números de Streaming TV ficam guardados por 3 horas depois que a Amazon gera o relatório deles: meta.report_ready_at diz quando.