Relatórios: comandos da CLI

Listar os tipos de relatório e os filtros de cada um.

reports list

Sem parâmetros.

screenrig reports list

Retorna data.items, cada um com o kind, o title, a description do relatório e os filtros que ele aceita (params), além dos formats de arquivo.

Gerar um relatório como linhas ou gravá-lo em um arquivo CSV, XLSX ou PDF.

reports show <kind> [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--group-by folder|screen|tag]
    [--folder-id ID [--direct]] [--tag TAG] [--campaign-id ID] [--advertiser NAME]
    [--format json|csv|xlsx|pdf] [--output FILE]

screenrig reports show fleet_health --group-by screen --from 2026-10-01 --to 2026-10-28
screenrig reports show proof_of_play --advertiser "Acme Corp" --format pdf --output acme-proof-of-play.pdf

O JSON retorna data.columns, data.rows, data.totals e data.notes; as linhas de um relatório por pasta trazem id, parent_id e depth para a estrutura, e a primeira linha é o projeto inteiro. Um arquivo responde com seu caminho, bytes e SHA-256. Um relatório paginado é gravado por inteiro, até 50000 linhas (data.truncated caso contrário). proof_of_play exige um projeto que venda tempo de anúncio nas próprias telas. O acesso Somente leitura com a capacidade reports basta.

Enviar um relatório por e-mail aos membros do projeto em uma programação.

reports subscriptions list
reports subscriptions show <id>
reports subscriptions create --name NAME --kind KIND --format pdf|xlsx|csv
    --recipients MEMBERS --cadence daily|weekly|monthly [--weekday DAY]
    [--day-of-month N] [--hour N] [--timezone ZONE] [--filter NAME=VALUE]
reports subscriptions update <id> [--name NAME] [--format pdf|xlsx|csv]
    [--recipients MEMBERS] [--filter NAME=VALUE] [--cadence daily|weekly|monthly]
    [--weekday DAY] [--day-of-month N] [--hour N] [--timezone ZONE]
    [--pause | --resume] [--expect-rev REVISION]
reports subscriptions delete <id>
reports subscriptions send <id>

screenrig reports subscriptions create --name "Monday fleet health" --kind fleet_health --cadence weekly --weekday monday --hour 7 --timezone America/Los_Angeles --format pdf --recipients ann@example.com,usr_01EXAMPLEPERSON0000
screenrig reports subscriptions update rsub_01EXAMPLESUB0000000000 --pause

Cada execução cobre o período anterior a ela em dias UTC: ontem, os sete dias anteriores ou o mês passado. Os destinatários precisam ser membros do projeto, e um membro que sai deixa de receber o relatório. update precisa de pelo menos uma alteração. send envia o relatório agora para o período que uma execução agora cobriria, sem mover a programação, e responde com a assinatura, incluindo last_status e last_error deste envio. Uma execução com falha é repetida e aparece como last_status failed com last_error; um anexo PDF ou XLSX com mais de 8 MiB não é enviado. Uma organização tem no máximo 50 assinaturas em todos os seus projetos. Ler exige a capacidade project e acesso Somente leitura; criar, alterar, excluir e enviar exigem acesso Gerenciar.

Listar as entradas de auditoria, as mais recentes primeiro.

audit list [--actor ID] [--actor-kind KIND] [--source SOURCE] [--resource-type TYPE]
    [--resource-id ID] [--action CODE] [--field POINTER] [--since TIME] [--until TIME]
    [--limit N] [--after CURSOR]

screenrig audit list --resource-type screen --resource-id scr_01EXAMPLESCREEN00000000
screenrig audit list --action 'playlist.*' --source cli --limit 20

Retorna data.items do mais recente para o mais antigo, cada um com actor (kind, id, name), source, action, resource (type, id, name) e changes, cada um com um path (um ponteiro JSON para o recurso), before e after; uma credencial aparece como (redacted) dos dois lados. seq e hash aparecem quando uma entrada é encadeada, em poucos segundos. data.next_cursor é null na última página. O acesso Somente leitura com a capacidade project basta.

Mostrar uma entrada de auditoria com o antes e o depois de cada campo alterado.

audit show <id>

screenrig audit show aud_01EXAMPLEENTRY0000000000

Retorna a entrada com path, before e after de cada campo alterado, quem fez a alteração e por qual superfície, e seu lugar na cadeia depois de encadeada.

Mostrar o cabeçalho da cadeia de auditoria para guardar como âncora.

audit head

Sem parâmetros.

screenrig audit head

Imprime a última entrada encadeada como SEQ:HASH, o piso de retenção em que a cadeia começa e quantas entradas aguardam o encadeamento. Guarde o cabeçalho: audit verify --anchor SEQ:HASH comprova depois que o histórico não foi reescrito nem truncado.

Recalcular a cadeia de hashes de auditoria e informar tudo o que não corresponder.

audit verify [--from-seq N] [--limit N] [--anchor SEQ:HASH]

screenrig audit verify --anchor 128:3f2c0b6e9a4d81c7f5e0a2b4c6d8e0f1a3b5c7d9e1f30415263748596a7b8c9d

Informa hash_mismatch, prev_mismatch, gap, head_mismatch, anchor_mismatch ou floor_mismatch por entrada em data.problems. Encerra com o código 13 e data.ok false quando a cadeia não é verificada; data.next_seq continua uma cadeia mais longa.

Gravar o registro de auditoria filtrado em um arquivo CSV, XLSX ou PDF.

audit export --format csv|xlsx|pdf [--output FILE]
    [--actor ID] [--actor-kind KIND] [--source SOURCE] [--resource-type TYPE]
    [--resource-id ID] [--action CODE] [--field POINTER] [--since TIME] [--until TIME]

screenrig audit export --format csv --output audit.csv
screenrig audit export --format pdf --resource-type playlist --output playlist-changes.pdf

Grava uma linha por campo alterado, da mais antiga para a mais recente, até 50000 linhas (data.truncated caso contrário), com o cabeçalho da cadeia e o piso de retenção no arquivo, e responde com seu caminho, bytes e SHA-256.

Ler registros por reprodução, uma linha por início visível.

playback plays [--from TIME] [--to TIME] [--screen-id ID] [--media-id ID] [--tag TAG] [--cursor CURSOR] [--limit N] [--all]
playback plays --format csv|xlsx|pdf [--output FILE] [--from TIME] [--to TIME] [--screen-id ID] [--media-id ID] [--tag TAG]

screenrig playback plays --from 7d --tag Lobby --all
screenrig playback plays --format csv --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z --output september-plays.csv
screenrig playback plays --format xlsx --from 7d --tag Lobby --output lobby-plays.xlsx

O CLI normaliza ambos os limites para UTC e os envia em cada solicitação; data.from e data.to os repetem. Os 5 segundos mais recentes são retidos até se estabilizarem, então uma reprodução aparece cerca de 5 segundos após ser recebida, e data.to reporta esse fim efetivo. Uma reprodução de aplicativo traz release_id e media_id vazio. JSON retorna uma página em data.items com data.next_cursor, e data.next.argv é o comando exato para a próxima página. --all para cedo, com data.next e um aviso, no limite de páginas (playback_plays_truncated) ou quando o orçamento de exportação é gasto (playback_export_rate_limited), em vez de gastar requisições até recusar.

O CSV está conforme RFC 4180 com a linha de cabeçalho fixa screen_id,playlist_id,page_id,primitive_id,media_id,primitive,started_at,received_at,manifest_revision,playlist_revision, tempos em RFC 3339 UTC. primitive_id e started_at estão vazios a menos que o Player os tenha reportado. Uma célula que começa com =, +, -, @, tabulação ou retorno de carro carrega um ' inicial para que planilhas não a avaliem. O CLI escreve através de um arquivo temporário privado no mesmo diretório e substitui um arquivo existente somente após o fluxo terminar limpo. --timeout é o limite de sem progresso para o fluxo, 60000 ms sem byte por padrão, não um limite para sua duração total. O envelope reporta path, bytes, rows, sha256, content_type, from, to e last_received_at; o CSV nunca entra no envelope. Com --output -, o CSV vai para stdout e nenhum envelope é impresso.

Se um stream falhar no meio, o comando sai com código diferente de zero e nunca grava o arquivo de destino. As linhas completas já recebidas permanecem em FILE.partial (FILE.partial-2 e assim por diante quando ele existe), e error.next exporta o restante do intervalo desde o último received_at para um FILE-rest.csv não usado. Linhas recebidas exatamente naquele instante aparecem em ambos, então descarte as repetições ao juntá-las. Com --output -, o CSV incompleto fica em stdout, e o erro e o comando next vão para stderr.

xlsx e pdf são renderizados no servidor e salvos da mesma forma, por meio de um arquivo temporário privado. O envelope informa path, bytes, sha256, content_type e format, e o arquivo contém as primeiras 50.000 linhas do intervalo.

Leia totais diários de reprodução para este projeto, dias mais recentes primeiro.

playback list [--screen-id ID] [--media-id ID] [--day YYYY-MM-DD | --day-from YYYY-MM-DD --day-to YYYY-MM-DD]
              [--format json|csv|xlsx|pdf] [--output FILE]

screenrig playback list --screen-id scr_01EXAMPLESCREEN00000000 --day 2026-08-14
screenrig playback list --format csv --day-from 2026-09-01 --day-to 2026-09-30
screenrig playback list --format pdf --day-from 2026-09-01 --day-to 2026-09-30 --output september.pdf

Uma linha por tela, objeto de mídia e dia UTC. Os filtros selecionam as linhas do próprio autor da chamada. O JSON retorna no máximo 200 linhas em data.items, do dia mais recente ao mais antigo; os totais diários são atualizados a cada 10 minutos, mais ou menos, e playback plays mostra inícios mais recentes. A linha de cabeçalho do CSV é screen_id,media_id,filename,primitive,day,play_count,last_page_id,last_manifest_revision,first_started_at,last_started_at. O CSV é uma solicitação gravada como um CSV de reproduções, e a resposta dele relata path, bytes, rows, sha256 e content_type; uma resposta xlsx ou pdf relata path, bytes, sha256, content_type e format. Uma exportação diária que falha não guarda nada; execute-a de novo.

Ler contagens de reprodução por dia UTC, ou classificar as telas ou mídias mais usadas.

playback totals [--by day|screen|media|screen_day] [--day-from YYYY-MM-DD] [--day-to YYYY-MM-DD]
                [--screen-id ID | --media-id ID] [--top N] [--format json|csv|xlsx|pdf] [--output FILE]

screenrig playback totals
screenrig playback totals --day-from 2026-09-01 --day-to 2026-09-30 --screen-id scr_01EXAMPLESCREEN00000000
screenrig playback totals --by screen --top 5
screenrig playback totals --by media --day-from 2026-09-01 --day-to 2026-09-30
screenrig playback totals --by screen_day --top 3
screenrig playback totals --by screen --top 10 --format xlsx --output busiest-screens.xlsx

As contagens vêm dos resumos diários, que seguem a ingestão em até cerca de 21 minutos; playback plays mostra inícios mais recentes. day responde data.days, screen e media respondem data.screens e data.media, e screen_day responde data.screen_days. Uma série diária abrange no máximo 366 dias (92 com --screen-id ou --media-id) e um ranking no máximo 92. data.truncated é true quando um ranking em uma janela muito grande para uma leitura manteve apenas as melhores chaves de cada fatia. Um formato de arquivo grava o arquivo do servidor em --output, e seu envelope informa path, bytes, sha256, content_type e format.

Lê quantas das reproduções numeradas pelos Players chegaram ao screenRIG por dia UTC e as lacunas em que reproduções se perderam.

playback completeness [--day-from YYYY-MM-DD] [--day-to YYYY-MM-DD] [--screen-id ID] [--limit N]
                      [--format json|csv|xlsx|pdf] [--output FILE]

screenrig playback completeness
screenrig playback completeness --day-from 2026-09-01 --day-to 2026-09-30
screenrig playback completeness --screen-id scr_01EXAMPLESCREEN00000000 --limit 20
screenrig playback completeness --format pdf --output completeness.pdf

Cada início de mídia carrega um número, então uma reprodução que uma tela fez e nunca entregou, como uma feita offline além da fila de relatório de 24 horas, deixa uma lacuna. data.completeness é data.measured_plays sobre data.measured_plays mais data.missing_plays para a janela, de 0 a 1, e null quando nenhum dos dois foi medido: reproduções sem número, de Players que não numeram suas reproduções ou de antes de passarem a numerá-las, não são medidas. data.days dá as mesmas três cifras para cada dia UTC que tiver alguma, do mais antigo ao mais recente, com a lacuna contada no dia da reprodução seguinte. data.gaps lista cada lacuna, das mais recentes às mais antigas, com screen_id, day, from e to (os horários de início das reproduções de cada lado) e missing_plays; --limit limita a lista, e data.truncated é true quando existem mais. Uma tela desligada não faz reproduções e não deixa lacuna. O resumo é atualizado a cada 10 minutos. Uma solicitação de API medida; o orçamento de exportação de reprodução não se aplica. Um formato de arquivo grava o arquivo do servidor em --output, e seu envelope informa path, bytes, sha256, content_type e format.