Relatórios: referência da API, endpoints e exemplos

OpenAPI YAML OpenAPI JSON problemas YAML Visão geral da API

Este grupo tem 8 operações, geradas a partir de api/openapi.yaml. Filtre por caminho, ação ou autenticação. Cada endpoint lista suas entradas; expanda-o para ver um modelo de solicitação e os códigos de resposta. Os modelos precisam de seus próprios valores e de um corpo válido conforme o esquema.

Substitua os espaços reservados em maiúsculas pelos seus valores. Para uma solicitação JSON, salve um corpo que corresponda ao esquema em request.json. Exemplos de cookies usam um jar local de cookies de uma sessão autenticada.

Relatórios: resumos por pasta e tag, arquivos CSV, XLSX e PDF e programações de e-mail

GET/api/reports¶

Listar os tipos de relatório

Lista os tipos de relatório que GET /api/reports/{kind} gera, com os filtros de cada um, e os formatos em que um relatório é gravado. Requer a capacidade de relatórios.

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: nenhum
ID da operação: listReportKinds

Parâmetros

Nome	Enviar	Obrigatório?	Descrição
ScreenRig-Project	cabeçalho	opcional	Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token.

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/reports'

Respostas

Status	Significado	Corpo e cabeçalhos
200	Os tipos de relatório.	ReportCatalog (application/json)
padrão	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)

GET/api/reports/{kind}¶

Obter um relatório

Gera um relatório a partir dos agregados do projeto (resumos de disponibilidade, linhas de alertas, estado das telas, entrega de campanhas diretas), nunca de eventos brutos. fleet_health, uptime, publishing e alerts agrupam por group_by folder (padrão), screen ou tag nos dias UTC inclusivos de from a to (padrão os últimos 30): uma pasta contém cada tela que há nela e em suas pastas filhas, e sua primeira linha é o projeto inteiro; folder_id limita o relatório a uma pasta e ao que ela contém, e com direct à pasta e às suas pastas filhas (ou, agrupado por tela, às telas que estão diretamente nela). alert_log lista cada alerta iniciado no período. proof_of_play soma as exibições das campanhas diretas do projeto por campanha, mídia e tela, para uma campaign_id ou todas as campanhas de um anunciante. format json (padrão) retorna a tabela; csv, xlsx e pdf retornam a mesma tabela como anexo. fleet_health em JSON está em todos os planos; qualquer outro tipo, e qualquer formato de arquivo, exige o recurso de relatórios do plano (402 feature_not_in_plan).

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: nenhum
ID da operação: getReport

Parâmetros

Nome	Enviar	Obrigatório?	Descrição
ScreenRig-Project	cabeçalho	opcional	Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token.
kind	caminho	obrigatório	O tipo de relatório (GET /api/reports).
formato	consulta	opcional	json (padrão) retorna o relatório como JSON. csv, xlsx e pdf retornam as mesmas linhas como anexo (cada página de um relatório paginado, até 50000 linhas).
de	consulta	opcional	Primeiro dia UTC, inclusivo. Padrão: 29 dias antes de to. No máximo 366 dias com to.
até	consulta	opcional	Último dia UTC, inclusivo. Padrão é hoje (UTC).
group_by	consulta	opcional	O que é uma linha. Não se aplica a alert_log nem proof_of_play.
folder_id	consulta	opcional	Somente esta pasta de telas e tudo o que ela contém.
direct	consulta	opcional	Com folder_id: somente as telas diretamente na pasta (group_by screen), ou a pasta e suas pastas filhas (group_by folder).
tag	consulta	opcional	Somente as telas com esta tag.
campaign_id	consulta	opcional	proof_of_play: uma campanha direta.
advertiser	consulta	opcional	proof_of_play: as campanhas deste anunciante ou patrocinador (nome exato, sem diferenciar maiúsculas).

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/reports/KIND'

Respostas

Status	Significado	Corpo e cabeçalhos
200	O relatório como tabela, ou como arquivo para csv, xlsx e pdf.	Relatório (application/json), string (text/csv), string (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), string (application/pdf); cabeçalhos: Cache-Control
400	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
402	feature_not_in_plan — Os relatórios fazem parte do Plus: todo tipo, exceto fleet_health em JSON, e csv, xlsx e pdf de qualquer tipo, os exigem. fleet_health em JSON (o formato padrão) está disponível em todos os planos, assim como os tipos de relatório e as exportações das rotas de relatório existentes. O problema nomeia o recurso, o plano do projeto e required_plan.	Problema (application/problem+json)
403	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
404	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
padrão	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)

GET/api/report-subscriptions¶

Listar as assinaturas de relatórios

Lista os relatórios programados do projeto, do mais antigo ao mais recente (no máximo 50), cada um com seu próximo envio e o resultado do último. Requer a capacidade do projeto.

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: nenhum
ID da operação: listReportSubscriptions

Parâmetros

Nome	Enviar	Obrigatório?	Descrição
ScreenRig-Project	cabeçalho	opcional	Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token.

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/report-subscriptions'

Respostas

Status	Significado	Corpo e cabeçalhos
200	As assinaturas de relatórios do projeto.	ReportSubscriptionList (application/json)
padrão	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)

POST/api/report-subscriptions¶

Criar assinatura de relatório

Programa o envio de um relatório por e-mail, como anexo PDF, XLSX ou CSV, todos os dias, semanas ou meses em um horário em um fuso horário.

Cada envio cobre o período anterior, em dias UTC: o dia anterior, os sete dias anteriores ou o mês passado. recipients são membros do projeto, indicados por user_id ou pelo endereço de e-mail do membro; qualquer outra pessoa é recusada, então uma assinatura nunca é um meio de escrever a um estranho, e um membro que sai deixa de recebê-la.

Uma execução que falha é repetida e aparece com last_status failed e last_error. No máximo 50 por organização em todos os seus projetos (report_subscription_limit_reached).

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: ReportSubscriptionWrite
ID da operação: createReportSubscription

Parâmetros

Nome	Enviar	Obrigatório?	Descrição
ScreenRig-Project	cabeçalho	opcional	Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token.
Idempotency-Key	cabeçalho	opcional	Omitir para uma operação nova. Forneça e reutilize uma chave para deduplicar tentativas; o CLI gerencia as chaves automaticamente.

Campos do corpo da solicitação

Campo	Descrição
nome (obrigatório, string)	minLength: 1 maxLength: 100
kind (obrigatório, string)	Valores permitidos: "fleet_health", "uptime", "publishing", "alerts", "alert_log", "proof_of_play"
filters (opcional, objeto)	Os filtros do relatório além dos dias (GET /api/reports os lista).
schedule (obrigatório, ReportSchedule)
format (obrigatório, string)	Valores permitidos: "pdf", "xlsx", "csv"
recipients (obrigatório, array)	user_id ou endereço de e-mail de membros do projeto.
habilitado (opcional, boolean)	padrão: true

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/report-subscriptions'

Respostas

Status	Significado	Corpo e cabeçalhos
201	Criada.	ReportSubscription (application/json); cabeçalhos: ETag
400	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
402	feature_not_in_plan — Os relatórios fazem parte do Plus. O problema nomeia o recurso, o plano do projeto e required_plan.	Problema (application/problem+json)
409	report_subscription_limit_reached.	Problema (application/problem+json)
padrão	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)

GET/api/report-subscriptions/{id}¶

Obter uma assinatura de relatório

Requer a capacidade do projeto.

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: nenhum
ID da operação: getReportSubscription

Parâmetros

Nome	Enviar	Obrigatório?	Descrição
ScreenRig-Project	cabeçalho	opcional	Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token.
id	caminho	obrigatório

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/report-subscriptions/RESOURCE_ID'

Respostas

Status	Significado	Corpo e cabeçalhos
200	Uma assinatura de relatório.	ReportSubscription (application/json); cabeçalhos: ETag
404	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
padrão	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)

PATCH/api/report-subscriptions/{id}¶

Atualizar uma assinatura de relatório

Altera qualquer um de name, filters, schedule, format, recipients e enabled; o tipo de relatório nunca muda. Uma programação alterada ou uma assinatura reativada recomeça na próxima ocorrência. If-Match traz a revisão lida (revision_conflict quando está desatualizada).

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: ReportSubscriptionPatch
ID da operação: updateReportSubscription

Parâmetros

Nome	Enviar	Obrigatório?	Descrição
ScreenRig-Project	cabeçalho	opcional	Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token.
id	caminho	obrigatório
Idempotency-Key	cabeçalho	opcional	Omitir para uma operação nova. Forneça e reutilize uma chave para deduplicar tentativas; o CLI gerencia as chaves automaticamente.
If-Match	cabeçalho	opcional	A revisão da assinatura, entre aspas ou sem elas.

Campos do corpo da solicitação

Campo	Descrição
nome (opcional, string)	minLength: 1 maxLength: 100
filters (opcional, objeto)
schedule (opcional, ReportSchedule)
format (opcional, string)	Valores permitidos: "pdf", "xlsx", "csv"
recipients (opcional, array)
habilitado (opcional, boolean)

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/report-subscriptions/RESOURCE_ID'

Respostas

Status	Significado	Corpo e cabeçalhos
200	Atualizada.	ReportSubscription (application/json); cabeçalhos: ETag
400	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
402	feature_not_in_plan — Os relatórios fazem parte do Plus; uma alteração que apenas desativa a assinatura continua disponível. O problema nomeia o recurso, o plano do projeto e required_plan.	Problema (application/problem+json)
404	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
409	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
padrão	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)

EXCLUIR/api/report-subscriptions/{id}¶

Excluir assinatura de relatório

Exclui a assinatura; nada mais é enviado.

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: nenhum
ID da operação: deleteReportSubscription

Parâmetros

Nome	Enviar	Obrigatório?	Descrição
ScreenRig-Project	cabeçalho	opcional	Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token.
id	caminho	obrigatório
Idempotency-Key	cabeçalho	opcional	Omitir para uma operação nova. Forneça e reutilize uma chave para deduplicar tentativas; o CLI gerencia as chaves automaticamente.

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/report-subscriptions/RESOURCE_ID'

Respostas

Status	Significado	Corpo e cabeçalhos
204	Excluído.	sem corpo
404	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
padrão	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)

POST/api/report-subscriptions/{id}/send¶

Enviar uma assinatura de relatório

Envia o relatório agora aos destinatários da assinatura, para o período que um envio programado cobriria agora, sem mover sua programação. A resposta é a assinatura com o resultado deste envio (last_status delivered ou failed, last_error).

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: nenhum
ID da operação: sendReportSubscription

Parâmetros

Nome	Enviar	Obrigatório?	Descrição
ScreenRig-Project	cabeçalho	opcional	Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token.
id	caminho	obrigatório
Idempotency-Key	cabeçalho	opcional	Omitir para uma operação nova. Forneça e reutilize uma chave para deduplicar tentativas; o CLI gerencia as chaves automaticamente.

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/report-subscriptions/RESOURCE_ID/send'

Respostas

Status	Significado	Corpo e cabeçalhos
200	A assinatura com o resultado deste envio.	ReportSubscription (application/json)
404	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)
padrão	Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico.	Problema (application/problem+json)