报告 API 参考：端点与示例

OpenAPI YAML OpenAPI JSON 问题 YAML API 概览

此分组有 8 个操作，由 api/openapi.yaml 生成。可按路径、操作或认证筛选。每个端点都会列出其输入；展开后可查看请求模板和响应代码。模板需要您自己的值和符合架构的请求体。

用你的值替换大写占位符。对于JSON请求，请保存符合request.json模式的请求体。Cookie示例使用经过身份验证会话的本地Cookie存储。

报告：按文件夹和标签的汇总、CSV、XLSX 和 PDF 文件以及邮件定时发送

GET/api/reports¶

列出报告类型

列出 GET /api/reports/{kind} 可生成的报告类型及各自的筛选条件，以及报告的输出格式。需要报告权限。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: listReportKinds

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。

请求模板和响应

shell · 请求模板

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

响应

状态	含义	正文和头部
200	报告类型。	ReportCatalog (application/json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/reports/{kind}¶

获取报告

根据项目的汇总数据（可用性汇总、告警行、屏幕状态、直接广告活动的投放）生成报告，从不使用原始事件。fleet_health、uptime、publishing 和 alerts 在 from 到 to 的含首尾 UTC 日期范围内（默认最近 30 天）按 group_by 的 folder（默认）、screen 或 tag 汇总：文件夹包含其中及所有子文件夹内的每块屏幕，其第一行是整个项目；folder_id 将报告限定为某个文件夹及其内容，加上 direct 则限定为该文件夹及其子文件夹（按屏幕分组时限定为直接位于其中的屏幕）。alert_log 列出周期内发生的每个告警。proof_of_play 按活动、媒体和屏幕汇总项目直接广告活动的播放次数，对象为一个 campaign_id 或某广告主的全部活动。format json（默认）返回表格；csv、xlsx 和 pdf 以附件形式返回同一张表。fleet_health 的 JSON 格式每个计划都包含；其他所有类型以及任何文件格式都需要“报告”计划功能（402 feature_not_in_plan）。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: getReport

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
kind	路径	必填	报告类型（GET /api/reports）。
格式	查询	可选	json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
起始	查询	可选	起始 UTC 日期（含）。默认为 to 之前 29 天。与 to 的跨度最多 366 天。
至	查询	可选	最后的UTC日，含当日。默认为今天（UTC）。
group_by	查询	可选	每行代表什么。不适用于 alert_log 或 proof_of_play。
folder_id	查询	可选	仅限此屏幕文件夹及其中的全部内容。
direct	查询	可选	与 folder_id 一起使用：仅限直接位于该文件夹中的屏幕（group_by screen），或该文件夹及其子文件夹（group_by folder）。
标签	查询	可选	仅限带有此标签的屏幕。
campaign_id	查询	可选	proof_of_play：一个直接广告活动。
advertiser	查询	可选	proof_of_play：该广告主或赞助商的广告活动（完整名称，不区分大小写）。

请求模板和响应

shell · 请求模板

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

响应

状态	含义	正文和头部
200	表格形式的报告；csv、xlsx 和 pdf 时为文件。	报告（application/json）、字符串（text/csv）、字符串（application/vnd.openxmlformats-officedocument.spreadsheetml.sheet）、字符串（application/pdf）；标头：Cache-Control
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
402	feature_not_in_plan — 报告属于 Plus：除 fleet_health 的 JSON 格式外，所有类型，以及任何类型的 csv、xlsx 和 pdf，都需要它。fleet_health 的 JSON 格式（默认格式）在每个计划中都开放，报告类型和现有报告路由的导出也是如此。该问题指明功能、项目的计划和 required_plan。	问题 (application/problem+json)
403	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/report-subscriptions¶

列出报告订阅

按时间从旧到新列出项目已排程的报告（最多 50 个），每个都含下次运行和上次运行的结果。需要项目权限。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: listReportSubscriptions

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。

请求模板和响应

shell · 请求模板

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

响应

状态	含义	正文和头部
200	项目的报告订阅。	ReportSubscriptionList (application/json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/report-subscriptions¶

创建报告订阅

安排以 PDF、XLSX 或 CSV 附件通过电子邮件发送报告，每天、每周或每月在某时区的指定整点发送。

每次运行覆盖其之前的周期（按 UTC 日）：前一天、前七天或上个月。recipients 是项目成员，用 user_id 或成员的电子邮件地址指定；其他人会被拒绝，因此订阅不会成为向外部人员发邮件的途径，离开项目的成员将不再收到。

失败的运行会重试，并以 last_status failed 和 last_error 显示。每个组织跨其所有项目最多 50 个（report_subscription_limit_reached）。

身份验证: projectBearer 或 dashboardSession
请求主体: ReportSubscriptionWrite
操作 ID: createReportSubscription

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
名称（必填，字符串）	minLength: 1 maxLength: 100
kind（必填，字符串）	允许的值："fleet_health", "uptime", "publishing", "alerts", "alert_log", "proof_of_play"
filters（可选，对象）	报告的日期以外的筛选条件（GET /api/reports 会列出）。
schedule（必填，ReportSchedule）
format（必填，字符串）	允许的值："pdf", "xlsx", "csv"
recipients（必填，数组）	项目成员的 user_id 或电子邮件地址。
启用（可选，布尔值）	默认：true

请求模板和响应

shell · 请求模板

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'

响应

状态	含义	正文和头部
201	已创建。	ReportSubscription（application/json）；标头：ETag
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
402	feature_not_in_plan — 报告属于 Plus。该问题指明功能、项目的计划和 required_plan。	问题 (application/problem+json)
409	report_subscription_limit_reached.	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

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

获取报告订阅

需要项目权限。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: getReportSubscription

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填

请求模板和响应

shell · 请求模板

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

响应

状态	含义	正文和头部
200	一个报告订阅。	ReportSubscription（application/json）；标头：ETag
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

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

更新报告订阅

可更改 name、filters、schedule、format、recipients 和 enabled 中的任意项；报告类型不可更改。更改排程或重新启用订阅后，从下一次排程开始。If-Match 携带所读取的修订号（过期时为 revision_conflict）。

身份验证: projectBearer 或 dashboardSession
请求主体: ReportSubscriptionPatch
操作 ID: updateReportSubscription

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。
If-Match	header	可选	订阅的修订号，可带引号或不带。

请求主体字段

字段	描述
名称（可选，字符串）	minLength: 1 maxLength: 100
filters（可选，对象）
schedule（可选，ReportSchedule）
format（可选，字符串）	允许的值："pdf", "xlsx", "csv"
recipients（可选，数组）
启用（可选，布尔值）

请求模板和响应

shell · 请求模板

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'

响应

状态	含义	正文和头部
200	已更新。	ReportSubscription（application/json）；标头：ETag
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
402	feature_not_in_plan — 报告属于 Plus；仅关闭订阅的更改仍然开放。该问题指明功能、项目的计划和 required_plan。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

删除/api/report-subscriptions/{id}¶

删除报告订阅

删除订阅；此后不再发送任何内容。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: deleteReportSubscription

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求模板和响应

shell · 请求模板

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

响应

状态	含义	正文和头部
204	已删除。	无正文
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

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

发送报告订阅

立即向订阅的收件人发送报告，覆盖现在按排程运行所对应的周期，不改变排程。响应为带有本次发送结果的订阅（last_status 为 delivered 或 failed，以及 last_error）。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: sendReportSubscription

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求模板和响应

shell · 请求模板

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

响应

状态	含义	正文和头部
200	带有本次发送结果的订阅。	ReportSubscription (application/json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)