Report: riferimento API, endpoint ed esempi

OpenAPI YAML OpenAPI JSON problemi YAML Panoramica dell’API

Questo gruppo ha 8 operazioni, generate da api/openapi.yaml. Filtra per percorso, azione o autenticazione. Ogni endpoint elenca i suoi input; espandilo per vedere un modello di richiesta e i codici di risposta. I modelli richiedono i tuoi valori e un corpo valido secondo lo schema.

Sostituisci i segnaposto maiuscoli con i tuoi valori. Per una richiesta JSON, salva un corpo che corrisponde allo schema in request.json. Gli esempi di cookie usano un cookie jar locale da una sessione autenticata.

Report: riepiloghi per cartella e tag, file CSV, XLSX e PDF e invii programmati via email

GET/api/reports¶

Elenca i tipi di report

Elenca i tipi di report che GET /api/reports/{kind} costruisce, con i filtri di ciascuno, e i formati in cui un report viene scritto. Richiede la capacità dei report.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listReportKinds

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	I tipi di report.	ReportCatalog (application/json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/reports/{kind}¶

Ottieni un report

Genera un report dagli aggregati del progetto (riepiloghi di disponibilità, righe di allarmi, stato degli schermi, consegna delle campagne dirette), mai da eventi grezzi. fleet_health, uptime, publishing e alerts raggruppano per group_by folder (predefinito), screen o tag sui giorni UTC inclusivi da from a to (predefinito gli ultimi 30): una cartella contiene ogni schermo al suo interno e nelle sue cartelle figlie, e la sua prima riga è l'intero progetto; folder_id limita il report a una cartella e a ciò che contiene, e con direct alla cartella e alle sue cartelle figlie (oppure, raggruppato per schermo, agli schermi direttamente al suo interno). alert_log elenca ogni allarme iniziato nel periodo. proof_of_play somma le riproduzioni delle campagne dirette del progetto per campagna, contenuto e schermo, per una campaign_id o tutte le campagne di un inserzionista. format json (predefinito) restituisce la tabella; csv, xlsx e pdf restituiscono la stessa tabella come allegato. fleet_health come JSON è in ogni piano; ogni altro tipo, e qualsiasi formato di file, richiede la funzione report del piano (402 feature_not_in_plan).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getReport

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
kind	path	obbligatorio	Il tipo di report (GET /api/reports).
formato	query	opzionale	json (predefinito) restituisce il report come JSON. csv, xlsx e pdf restituiscono le stesse righe come allegato (ogni pagina di un report a pagine, fino a 50000 righe).
da	query	opzionale	Primo giorno UTC, incluso. Predefinito: 29 giorni prima di to. Al massimo 366 giorni con to.
a	query	opzionale	Ultimo giorno UTC, incluso. Predefinito a oggi (UTC).
group_by	query	opzionale	Cos'è una riga. Non per alert_log o proof_of_play.
folder_id	query	opzionale	Solo questa cartella di schermi e tutto ciò che contiene.
direct	query	opzionale	Con folder_id: solo gli schermi direttamente nella cartella (group_by screen), oppure la cartella e le sue cartelle figlie (group_by folder).
tag	query	opzionale	Solo gli schermi con questo tag.
campaign_id	query	opzionale	proof_of_play: una campagna diretta.
advertiser	query	opzionale	proof_of_play: le campagne di questo inserzionista o sponsor (nome esatto, senza distinzione tra maiuscole e minuscole).

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Il report come tabella, o come file per csv, xlsx e pdf.	Report (application/json), stringa (text/csv), stringa (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), stringa (application/pdf); intestazioni: Cache-Control
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
402	feature_not_in_plan — I report fanno parte di Plus: ogni tipo tranne fleet_health come JSON, e csv, xlsx e pdf di qualsiasi tipo, li richiedono. fleet_health come JSON (il formato predefinito) è in ogni piano, così come i tipi di report e le esportazioni delle rotte di report esistenti. Il problema indica la funzione, il piano del progetto e required_plan.	Problema (application/problem+json)
403	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/report-subscriptions¶

Elenca gli abbonamenti ai report

Elenca i report programmati del progetto, dal più vecchio (al massimo 50), ciascuno con il prossimo invio e l'esito dell'ultimo. Richiede la capacità del progetto.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listReportSubscriptions

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Gli abbonamenti ai report del progetto.	ReportSubscriptionList (application/json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/report-subscriptions¶

Crea abbonamento a un report

Programma l'invio di un report via email, come allegato PDF, XLSX o CSV, ogni giorno, settimana o mese a un'ora in un fuso orario.

Ogni invio copre il periodo precedente, in giorni UTC: il giorno prima, i sette giorni precedenti o il mese scorso. recipients sono membri del progetto, indicati con user_id o con l'indirizzo email del membro; chiunque altro viene rifiutato, quindi un abbonamento non è mai un modo per scrivere a un estraneo, e un membro che se ne va smette di riceverlo.

Un’esecuzione che fallisce viene ripetuta e compare con last_status failed e last_error. Al massimo 50 per organizzazione in tutti i suoi progetti (report_subscription_limit_reached).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ReportSubscriptionWrite
ID operazione: createReportSubscription

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
nome (obbligatorio, stringa)	minLength: 1 maxLength: 100
kind (obbligatorio, stringa)	Valori ammessi: "fleet_health", "uptime", "publishing", "alerts", "alert_log", "proof_of_play"
filters (opzionale, oggetto)	I filtri del report diversi dai giorni (GET /api/reports li elenca).
schedule (obbligatorio, ReportSchedule)
format (obbligatorio, stringa)	Valori ammessi: "pdf", "xlsx", "csv"
recipients (obbligatorio, array)	user_id o indirizzo email di membri del progetto.
abilitato (opzionale, booleano)	predefinito: true

Modello richiesta e risposte

shell · modello richiesta

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'

Risposte

Stato	Significato	Corpo e intestazioni
201	Creato.	ReportSubscription (application/json); intestazioni: ETag
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
402	feature_not_in_plan — I report fanno parte di Plus. Il problema indica la funzione, il piano del progetto e required_plan.	Problema (application/problem+json)
409	report_subscription_limit_reached.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

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

Ottieni un abbonamento a un report

Richiede la capacità del progetto.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getReportSubscription

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Un abbonamento a un report.	ReportSubscription (application/json); intestazioni: ETag
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

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

Aggiorna un abbonamento a un report

Modifica uno qualsiasi tra name, filters, schedule, format, recipients ed enabled; il tipo di report non cambia mai. Una programmazione modificata o un abbonamento riattivato riparte dalla prossima occorrenza. If-Match porta la revisione letta (revision_conflict se è obsoleta).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ReportSubscriptionPatch
ID operazione: updateReportSubscription

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.
If-Match	intestazione	opzionale	La revisione dell'abbonamento, tra virgolette o senza.

Campi del corpo della richiesta

Campo	Descrizione
nome (opzionale, stringa)	minLength: 1 maxLength: 100
filters (opzionale, oggetto)
schedule (opzionale, ReportSchedule)
format (opzionale, stringa)	Valori ammessi: "pdf", "xlsx", "csv"
recipients (opzionale, array)
abilitato (opzionale, booleano)

Modello richiesta e risposte

shell · modello richiesta

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'

Risposte

Stato	Significato	Corpo e intestazioni
200	Aggiornato.	ReportSubscription (application/json); intestazioni: ETag
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
402	feature_not_in_plan — I report fanno parte di Plus; una modifica che disattiva soltanto l’abbonamento resta disponibile. Il problema indica la funzione, il piano del progetto e required_plan.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

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

Elimina abbonamento a un report

Elimina l'abbonamento; non viene più inviato nulla.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: deleteReportSubscription

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
204	Eliminato.	nessun corpo
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

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

Invia un abbonamento a un report

Invia ora il report ai destinatari dell'abbonamento, per il periodo che un invio programmato coprirebbe ora, senza spostare la programmazione. La risposta è l'abbonamento con l'esito di questo invio (last_status delivered o failed, last_error).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: sendReportSubscription

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	L'abbonamento con l'esito di questo invio.	ReportSubscription (application/json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)