Skip to main content
GET
Get ai usage analytics report
The organization bot token must have the following scopes:
  • analytics:ai-analytics
Authenticate the report request with an organization bot bearer credential. Supply the workspace UUID in workspace_id and the report UUID in job_id. A live bot in the same organization with the current analytics:ai-analytics scope can fetch a report created by another bot. Completed reports include download_url and link_expires_at when the file is available. Follow that URL directly; it contains a derived organization bot file token and needs no additional Authorization header. Downloads use the configured secure file host (file.notion.com or file.notion.so; local environments use their configured file host). Links expire after seven days or at the saved file expiry, whichever comes first. Files retain their original 30-day lifetime. Fetch the report again to renew a link while its file remains available. Permissions, credential revocation, and file expiry are checked again when downloading. Expired or definitively missing files return HTTP 200 with status: "expired" and no download URL. Queued, running, and failed reports also omit download URLs. Storage failures and integrity mismatches remain errors. Treat the full download URL as a credential. Do not log or share it, and avoid sending it in referrers. Report responses and downloaded files use Cache-Control: private, no-store.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version
enum<string>
required

The Admin API version to use for this request.

Available options:
2026-06-01

Path Parameters

job_id
string<uuid>
required

Query Parameters

workspace_id
string<uuid>
required

Response

Report status and an available download link

object
string
required

Always analytics_report

Allowed value: "analytics_report"
id
string
required
report_type
enum<string>
required

One of: user_activity, content_pages, ai_usage

Available options:
user_activity,
content_pages,
ai_usage
report_version
integer
required
workspace_id
string<uuid>
required
start_date
string<date>
required
end_date
string<date>
required
time_zone
string
required
file_format
enum<string>
required

One of: csv, jsonl

Available options:
csv,
jsonl
status
enum<string>
required

One of: queued, running, completed, failed, expired

Available options:
queued,
running,
completed,
failed,
expired
created_time
string<date-time>
required
completed_time
string<date-time>
file_expires_at
string<date-time>
row_count
integer
file_size_bytes
integer
data_as_of
integer
download_url
string<uri>