Reports API Reference: Endpoints and Examples

OpenAPI YAML OpenAPI JSON problems YAML API overview

This group has 8 operations, generated from api/openapi.yaml. Filter by path, action, or authentication. Each endpoint lists its inputs; expand it for a request template and response codes. Templates need your own values and a schema-valid body.

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

Reports: folder and tag rollups, CSV, XLSX and PDF files and scheduled email

GET/api/reports¶

List Report Kinds

Lists the report kinds GET /api/reports/{kind} builds, with the filters each takes, and the formats a report is written in. Needs the reports capability.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listReportKinds

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

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

Responses

Status	Meaning	Body and headers
200	The report kinds.	ReportCatalog (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/reports/{kind}¶

Get Report

Builds a report from the project's aggregates (uptime rollups, the alert rows, screen state, direct campaign delivery), never from raw events. fleet_health, uptime, publishing and alerts roll up by group_by folder (default), screen or tag over the inclusive UTC days from to to (default the last 30): a folder holds every screen in it and in every folder inside it, and its first row is the whole project; folder_id limits the report to a folder and what it holds, and with direct to the folder and its child folders (or, grouped by screen, to the screens directly in it). alert_log lists each alert that began in the period. proof_of_play totals the plays of the project's direct campaigns per campaign, media and screen, for one campaign_id or every campaign of an advertiser. format json (default) returns the table; csv, xlsx and pdf return the same table as a file attachment. fleet_health as JSON is in every plan; every other kind, and any file format, needs the reports plan feature (402 feature_not_in_plan).

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getReport

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
kind	path	required	The report kind (GET /api/reports).
format	query	optional	json (default) returns the report as JSON. csv, xlsx and pdf return the same rows as a file attachment (every page of a paged report, up to 50000 rows).
from	query	optional	First UTC day, inclusive. Defaults to 29 days before to. At most 366 days with to.
to	query	optional	Last UTC day, inclusive. Defaults to today (UTC).
group_by	query	optional	What a row is. Not for alert_log or proof_of_play.
folder_id	query	optional	Only this screen folder and everything inside it.
direct	query	optional	With folder_id: only the screens directly in the folder (group_by screen), or the folder and its child folders (group_by folder).
tag	query	optional	Only screens carrying this tag.
campaign_id	query	optional	proof_of_play: one direct campaign.
advertiser	query	optional	proof_of_play: the campaigns of this advertiser or sponsor (exact name, any case).

Request template and responses

shell · request template

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

Responses

Status	Meaning	Body and headers
200	The report as a table, or as a file for csv, xlsx and pdf.	Report (application/json), string (text/csv), string (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), string (application/pdf); headers: Cache-Control
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
402	feature_not_in_plan — Reports are part of Plus: every kind but fleet_health as JSON, and csv, xlsx and pdf of any kind, need them. fleet_health as JSON (the default format) is open in every plan, as are the report kinds and the existing report routes' exports. The problem names the feature, the project's plan and required_plan.	Problem (application/problem+json)
403	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/report-subscriptions¶

List Report Subscriptions

Lists the project's scheduled reports, oldest first (at most 50), each with its next run and the outcome of its last. Requires the project capability.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listReportSubscriptions

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

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

Responses

Status	Meaning	Body and headers
200	The project's report subscriptions.	ReportSubscriptionList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/report-subscriptions¶

Create Report Subscription

Schedules a report to be emailed, as a PDF, XLSX or CSV attachment, daily, weekly or monthly at an hour in a time zone.

Each run covers the period before it in UTC days: yesterday, the seven days before, or last month. recipients are members of the project, named by user_id or by the email address of the member; anyone else is refused, so a subscription is never a way to mail an outsider, and a member who leaves stops receiving it.

A failed run is retried and shows as last_status failed with last_error. At most 50 per organization across its projects (report_subscription_limit_reached).

Authentication: projectBearer OR dashboardSession
Request body: ReportSubscriptionWrite
Operation ID: createReportSubscription

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 100
kind (required, string)	Allowed: "fleet_health", "uptime", "publishing", "alerts", "alert_log", "proof_of_play"
filters (optional, object)	The report's filters other than the days (GET /api/reports lists them).
schedule (required, ReportSchedule)
format (required, string)	Allowed: "pdf", "xlsx", "csv"
recipients (required, array)	user_id or email address of project members.
enabled (optional, boolean)	default: true

Request template and responses

shell · request template

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'

Responses

Status	Meaning	Body and headers
201	Created.	ReportSubscription (application/json); headers: ETag
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
402	feature_not_in_plan — Reports are part of Plus. The problem names the feature, the project's plan and required_plan.	Problem (application/problem+json)
409	report_subscription_limit_reached.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

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

Get Report Subscription

Requires the project capability.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getReportSubscription

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request template and responses

shell · request template

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

Responses

Status	Meaning	Body and headers
200	One report subscription.	ReportSubscription (application/json); headers: ETag
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

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

Update Report Subscription

Changes any of name, filters, schedule, format, recipients and enabled; the report kind never changes. A changed schedule or a re-enabled subscription restarts at its next occurrence. If-Match carries the revision read (revision_conflict when stale).

Authentication: projectBearer OR dashboardSession
Request body: ReportSubscriptionPatch
Operation ID: updateReportSubscription

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.
If-Match	header	optional	The subscription's revision, quoted or bare.

Request body fields

Field	Description
name (optional, string)	minLength: 1 maxLength: 100
filters (optional, object)
schedule (optional, ReportSchedule)
format (optional, string)	Allowed: "pdf", "xlsx", "csv"
recipients (optional, array)
enabled (optional, boolean)

Request template and responses

shell · request template

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'

Responses

Status	Meaning	Body and headers
200	Updated.	ReportSubscription (application/json); headers: ETag
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
402	feature_not_in_plan — Reports are part of Plus; a change that only turns the subscription off stays open. The problem names the feature, the project's plan and required_plan.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

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

Delete Report Subscription

Deletes the subscription; nothing more is sent.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deleteReportSubscription

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

shell · request template

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

Responses

Status	Meaning	Body and headers
204	Deleted.	no body
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

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

Send Report Subscription

Emails the report to the subscription's recipients now, for the period a scheduled run now would cover, without moving its schedule. The answer is the subscription with the outcome of this send (last_status delivered or failed, last_error).

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: sendReportSubscription

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

shell · request template

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

Responses

Status	Meaning	Body and headers
200	The subscription with the outcome of this send.	ReportSubscription (application/json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)