API de Eventos do projeto

Lista eventos duráveis do projeto em ordem crescente por sequência.

Paginação é contígua: passe o next_cursor retornado como after para continuar exatamente onde a página parou. next_cursor é o cursor do último evento retornado enquanto eventos mais novos já existem, e nulo no fim do histórico. limit padrão é 50 e aceita 1-200; valor fora desse intervalo é recusado com invalid_request e um membro errors[] nomeando limit.

Paginação por offset não é suportada. source=log lista o log do Player em vez disso: os relatórios de condição enviados pelos Players (runtime.reported) em ordem crescente pelo tempo de recebimento, filtrados por screen_id e severidade em uma janela de até (por padrão as últimas 24 horas, no máximo 31 dias).

Seus cursores são opacos: lg1_ ou ev1_ conforme onde o servidor mantém o log do Player, então devolva o que uma página retornou; um cursor do outro tipo é recusado com invalid_request nomeando o campo. Registros do log do Player não têm sequência, não estão em GET /stream/project e não são entregues a webhooks.

Um registro é reconhecido quando a fila de log do Player o aceita e é mantido para a retenção de eventos do projeto. Uma consulta com o último cursor e a janela padrão segue o log. Registros de log do Player não estão na lista padrão (source=project). from e to são recusados com invalid_request a menos que source seja log.

A lista do projeto aceita screen_id, playlist_id e application_id para ler os eventos de uma tela, playlist ou aplicativo, todos limitados ao projeto da credencial (um id nomeia quais eventos ler, nunca de quem): screen_id mantém os eventos cujo recurso é essa tela; playlist_id os eventos cujo recurso é essa playlist mais os eventos que a nomeiam como details.playlist_id (uma tela que a usa); application_id os eventos cujo recurso é esse aplicativo mais os que têm esse id como application_id (seus lançamentos e entradas chave/valor).

Um valor que não é um id do seu tipo é recusado com invalid_request nomeando o campo; playlist_id e application_id são recusados com source=log, cujos registros pertencem só a uma tela.

Ambas as fontes usam resource_id, tipo e severidade (mínimo), combinados entre si, com os filtros de ID e paginação; um registro de log do Player é um registro runtime.reported cujo recurso é sua tela, então um resource_id que não seja essa tela ou um tipo que exclua runtime.reported retorna uma página vazia. before (ou order=desc) mostra os mais recentes primeiro: next_cursor é o cursor do item mais antigo retornado e passado de volta como before para continuar para itens mais antigos.

Sem from, uma página source=log mais recente primeiro alcança além das 24 horas padrão até o registro mais antigo que a retenção de eventos do projeto mantém, no máximo 31 dias abaixo da borda superior da página por requisição. Uma página source=log mais recente primeiro pode conter menos que o limite de registros, até nenhum, com um next_cursor; null ainda a encerra, no fim do log retido.

Um chamador limitado a telas (docs/screen-scope.md) lê um feed filtrado: eventos de telas dentro do seu escopo, das pastas de telas que ele pode ver (as suas próprias, as pastas acima e as de dentro; screen.moved somente quando o destino está dentro do seu escopo), de campanhas, playlists, mídia, aplicativos e cartões, e as revisões playlist_change.

Todo outro evento fica de fora, então uma página pode conter menos eventos que limit, até nenhum, com um next_cursor; continue paginando com ele. source=log precisa de um screen_id dentro do seu escopo. Eventos sobre o próprio projeto não são enviados.

Stream de escuta reproduzível do projeto. Os registros de log do player (runtime.reported) são lidos com GET /api/events?source=log e não estão neste stream. Abrir esta requisição custa 1 crédito, como a inscrição no stream de escuta. Os cabeçalhos de crédito são omitidos. Os eventos faturados seguintes custam 1 crédito cada; screen.*, runtime.*, alert_mute.* e application.event são isentos.

Heartbeats e o preâmbulo de retry nunca são cobrados. stream.cursor e stream.resync_required são faturados. A idempotência de débito é sse-event:<project_id>:<sequence>, então a reconexão e replay são gratuitos. Um evento faturado não pago não é gravado e o stream fecha.

Um stream aberto com uma sessão de dashboard não cobra nada (nem a abertura nem os seus eventos), como as requisições de API do dashboard; ele ainda ocupa um dos slots de stream do projeto. Um chamador limitado a telas (docs/screen-scope.md) recebe o mesmo feed filtrado que GET /api/events: nenhum frame é enviado para um evento descartado e stream.cursor continua avançando a posição.

O escopo é lido quando o stream abre, e a árvore de pastas de novo em um evento de movimentação ou de pasta; um escopo reduzido vale para um stream aberto quando ele se reconecta.