Skip to main content
GET
Get credit usage for an agent in a space
The organization bot token must have the following scopes:
  • workflows:read
This endpoint also reports usage for lite database Autofill agents, including those with zero premium AI credit usage or those moved to Trash.

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

agent_id
string<uuid>
required

The ID of a custom agent or database Autofill agent.

space_id
string<uuid>
required

Query Parameters

start_cursor
string

Pagination cursor returned from a previous response's next_cursor; paginates credit_per_billing_period_list (newest period first).

Response

credit_per_billing_period_list
object[]
required
has_more
boolean
required

Whether more billing periods are available.

id
string<uuid>
required
runs_completed
number
required

All-time count of finished (success or failure) runs for this agent.

status
enum<string>
required

Agent status; same values as the list-agents endpoint's status field.

Available options:
active,
credit_limit,
deleted,
disabled_by_notion,
disabled_due_to_lack_of_editors,
disabled_due_to_lack_of_full_access_members,
disabled_from_agent_settings,
disabled_from_api,
disabled_from_workspace_settings,
disabled_from_workspace_settings_but_resumable,
failure_limit,
internal_error,
mark_session_failed_autopause,
needs_review,
run_limit,
runaway_credit_usage,
tool_unavailable,
workspace_credit_limit
total_credits_used
number
required

All-time premium AI credits consumed by this agent across every period.

type
enum<string>
required

Custom agents vs database (autofill) agents.

Available options:
custom,
database_autofill
created_by_id
string<uuid>
credit_limit
number

Enforced per-agent credit limit, if one is configured.

last_credit_usage_time
number

Epoch ms of the agent's most recent premium-credit usage; omitted if the agent has never consumed credits.

name
string
next_cursor
string

Cursor to fetch the next page of credit_per_billing_period_list; omitted when has_more is false.