Agents
Retrieve an agent
Retrieve metadata for one accessible Custom Agent or the personal agent.
GET
TypeScript SDK
Pass
notion_ai as the agent_id to retrieve the personal agent (Notion AI) of the user a personal access token acts as. Its id and agent_type are both notion_ai. Any other token receives a 404 object_not_found.
Favorites
is_favorited is true or false for a personal access token and null for a connection token, which has no personal favorites scope. For notion_ai, it is false for a personal access token.Authorizations
Headers
The API version to use for this request. The latest version is 2026-03-11.
Available options:
2026-03-11 Path Parameters
Query Parameters
Response
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 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, owner_allowance_limit, failure_limit, mark_session_failed_autopause, disabled_from_workspace_settings, disabled_from_workspace_settings_but_resumable, 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