Skip to main content
GET
TypeScript SDK

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 API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Path Parameters

agent_id
required

The agent ID (a UUID), or notion_ai for the personal agent. Endpoint-specific restrictions still apply.

Query Parameters

verbose
boolean

Whether to include the agent's inline instructions. Defaults to false.

Response

object
string
required

Always agent

Allowed value: "agent"
id
required
agent_type
enum<string>
required

What kind of agent this is: "notion_ai" is the personal agent; "custom_agent" is a standalone agent you chat with; "autofill_custom_agent" fills a database property; "external" runs through an external provider.

Available options:
notion_ai,
custom_agent,
autofill_custom_agent,
external
name
string
required
description
string | null
required
instructions_page_id
string<uuid> | null
required
icon
Emoji · object
required
model
object
required

The model the agent runs on: auto (Notion selects) or a pinned model.

connections
object[]
required

Integrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions.

Maximum array length: 100
status
enum<string>
required

"active" when the agent can run; "disabled" when it is paused (see pause_reason); "deleted" when it has been removed.

Available options:
active,
disabled,
deleted
pause_reason
enum<string> | null
required

Why the agent is paused when status is "disabled" (e.g. "credit_limit", "disabled_from_workspace_settings"); null when active.

Available options:
run_limit,
credit_limit,
runaway_credit_usage,
workspace_credit_limit,
failure_limit,
mark_session_failed_autopause,
disabled_from_workspace_settings,
disabled_from_api,
disabled_from_agent_settings,
disabled_due_to_no_members_with_access,
disabled_due_to_lack_of_editors,
disabled_by_notion,
internal_error,
needs_user_review,
tool_unavailable
created_by
object | null
required
version
object | null
required
agent_version
object | null
required
has_unpublished_changes
required

Whether the draft has edits not yet in the published version, or "hidden" when the caller lacks edit access to the agent.

last_run_time
required

ISO 8601 timestamp of the agent's most recent run, null if it has never run, or "hidden" when the caller lacks edit access to the agent.

Pattern: ^\d{4}-\d{2}-\d{2}T
last_run_at
required

ISO 8601 timestamp of the agent's most recent run, null if it has never run, or "hidden" when the caller lacks edit access to the agent.

Pattern: ^\d{4}-\d{2}-\d{2}T
credit_limit
required

The per-agent credit limit that applies to this agent, null when uncapped, or "hidden" when the caller lacks full access to the agent. This is the effective limit computed at runtime, folding in both the agent's own limit and any workspace-admin default.

Required range: x >= 0
triggers
object[]
required

The agent's configured triggers, each with a machine type, an enabled flag, and (for recurrence triggers) a structured schedule.

Maximum array length: 100
created_time
string<date-time>

Date and time when this agent was created.

last_edited_time
string<date-time>

Date and time when this agent was last edited.

instructions
string | null

The agent's inline instructions when verbose=true, or null when its instructions are stored on a page.