Métricas de eventos

Estes dois endpoints, sob o prefixo /events, relatam a entrega dos eventos server-side da conta dona do token; um token só de leitura basta, e a resposta segue o envelope e o formato de data da API.

O account_id vem do token, não de um parâmetro.

GET /events/stats

Retorna a série temporal agregada de entregas da conta: por intervalo de tempo, quantos eventos tiveram sucesso e quantos deram erro.

Parâmetro	Tipo	Padrão	Descrição
`channels`	lista separada por vírgula	todos os canais	Códigos curtos de canal a incluir, itens trimados (ex.: `fb,ga`). Valores aceitos: `fb` (Facebook), `ga` (Google Analytics), `gads` (Google Ads), `tt` (TikTok), `li` (LinkedIn), `pin` (Pinterest). O filtro casa verbatim: um valor fora dessa lista (ex.: `facebook`) retorna 200 com série vazia.
`since`	timestamp (naive datetime)	7 dias antes do momento da consulta	Início da janela.
`until`	timestamp (naive datetime)	o momento da consulta	Fim da janela.
`step`	enum	`day`	Intervalo de agregação de cada ponto. Valores: `minute`, `hour`, `day`, `week`, `year`, `all` (ex.: `step=day`). Os nomes em PascalCase (`Day` etc.) ainda são aceitos como alias legado.

Resposta: JSON envelopado pela API. O corpo real é { "Ok": { "data": [...] } }; { "data": [...] } é apenas o valor interno do envelope Ok (ver Convenções e erros). Um objeto por intervalo de tempo, ordenado por epoch decrescente, até 1000 pontos.

Alcance histórico: cerca de 180 dias, pela política de retenção. Um since mais antigo volta vazio.

json

{
  "Ok": {
    "data": [
      { "epoch": "2026-07-21T00:00:00", "successes": 1240, "errors": 7 }
    ]
  }
}

Campo	Descrição
`epoch`	Início do intervalo. Apesar do nome, é serializado como string de datetime ISO-8601 naive (ex.: `"2026-07-21T00:00:00"`), não um inteiro Unix.
`successes`	Eventos entregues no intervalo.
`errors`	Eventos com falha no intervalo.

Nota

A taxa de erro não é um campo retornado. Você a deriva de /events/stats: errors / (successes + errors) por intervalo, ou somando os intervalos da janela.

GET /events/errors

Retorna o detalhamento linha a linha dos eventos que falharam, como CSV.

Parâmetro	Tipo	Padrão	Descrição
`channel`	string	todos os canais	Um único código curto de canal a filtrar (singular, diferente de `channels` em `/events/stats`), com os mesmos valores: `fb`, `ga`, `gads`, `tt`, `li`, `pin`. Casa exato.
`since`	timestamp (naive datetime)	7 dias antes do momento da consulta	Início da janela.
`until`	timestamp (naive datetime)	o momento da consulta	Fim da janela.

Aviso

Aqui o parâmetro é channel, no singular. Mandar o plural channels (como em /events/stats) não dá erro: a API ignora o parâmetro desconhecido e o CSV volta com todos os canais, sem filtro.

Resposta: CSV (text/csv, não JSON), até 10000 linhas. A linha de cabeçalho é emitida junto ao primeiro registro; quando nenhuma linha casa, o corpo vem completamente vazio, sem nem o cabeçalho. A conta retém só as 10000 linhas de erro mais recentes; esse teto é o histórico de erros inteiro, então estreitar a janela não pagina além dele. As colunas, nesta ordem:

Coluna	Descrição
`channel`	Canal de destino do evento.
`reference`	Identificador de destino do canal. Seu significado depende do canal: `pixel_id` (fb), `measurement_id` (ga), `pixel_code` (tt), `conversion_urn` (li), `ad_account_id` (pin), `customer_id` do Google Ads (gads).
`happened_at`	Momento do evento.
`event_name`	Nome do evento. Extraído do formato do Facebook; vazio para outros canais.
`status_code`	Código de status da resposta do provedor.
`error_title`	Título do erro. Extraído do formato do Facebook; vazio para outros canais.
`error_message`	Mensagem do erro. Extraída do formato do Facebook; vazia para outros canais.
`response`	Payload bruto completo da resposta do provedor.
`received`	Payload bruto completo recebido.
`sent`	Payload bruto completo enviado ao provedor.

Veja também

Relatórios: a referência irmã de relatórios da conta.
Autenticação: o token de conta que estes endpoints exigem.
Convenções e erros: envelope de resposta, formato de data.