Retrieve an agent
Retrieve metadata for one accessible Custom Agent.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
The API version to use for this request. The latest version is 2026-03-11.
2026-03-11 Path Parameters
The agent ID (a UUID), or notion_ai for the personal agent. Endpoint-specific restrictions still apply.
Query Parameters
Whether to include the agent's inline instructions. Defaults to false.
Response
Always agent
"agent"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.
notion_ai, custom_agent, autofill_custom_agent, external - Emoji
- File
- External
- Custom Emoji
- Icon
- Option 6
The model the agent runs on: auto (Notion selects) or a pinned model.
- Option 1
- Option 2
Integrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions.
100- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
"active" when the agent can run; "disabled" when it is paused (see pause_reason); "deleted" when it has been removed.
active, disabled, deleted Why the agent is paused when status is "disabled" (e.g. "credit_limit", "disabled_from_workspace_settings"); null when active.
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 Whether the draft has edits not yet in the published version, or "hidden" when the caller lacks edit access to the agent.
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.
^\d{4}-\d{2}-\d{2}TISO 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.
^\d{4}-\d{2}-\d{2}TThe 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.
x >= 0The agent's configured triggers, each with a machine type, an enabled flag, and (for recurrence triggers) a structured schedule.
100Date and time when this agent was created.
Date and time when this agent was last edited.
The agent's inline instructions when verbose=true, or null when its instructions are stored on a page.