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. credits_used_by_type breaks usage down into Notion, Select, and Standard credits. Learn what each credit type covers. credits_used counts only Notion credits, so the credits in credits_used_by_type don’t add up to credits_used.

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
credit_source
enum<string>
required

Whose credits the agent spends: its owner's ("owner") or the workspace's ("workspace").

Available options:
owner,
workspace
has_more
boolean
required

Whether more billing periods are available.

id
string<uuid>
required
object
string
required

Always agent_credit_usage

Allowed value: "agent_credit_usage"
owner_user_id
string<uuid> | null
required

User ID of the member who owns the agent and pays for it when credit_source is "owner"; null when the agent has no owner.

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,
owner_allowance_limit,
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. Values of 1 or more are whole credits, and values below 1 have at most two significant figures. Both round down.

type
enum<string>
required

Custom agents vs database (autofill) agents.

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

Credit limit enforced on the agent for its credit source, if any. Owner-funded agents only honor the limit set by the agent's editors.

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.