Agents

Get agent

Changed on
get/v1/agents/{agent_id}

Request

  • Base URL
    https://api.notion.com
  • URL
    https://api.notion.com/v1/agents/{agent_id}
  • Auth
    HTTP bearer

Path parameters

string required
OR
'notion_ai' | '33333333-3333-3333-3333-333333333333' required

One of: notion_ai, 33333333-3333-3333-3333-333333333333

Query parameters

verboseboolean

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

Headers

Notion-Version'2026-03-11' required

The API version to use for this request. The latest version is 2026-03-11.

Response

object'agent' required

Always agent

agent_type'notion_ai' | 'custom_agent' | 'autofill_custom_agent' | 'external' 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.

namestring required
descriptionstring nullable required
instructions_page_idstring uuid required
status'active' | 'disabled' | 'deleted' required

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

pause_reason'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' nullable required

One of: 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

is_favoritedboolean nullable required

Whether this agent is in the caller's personal favorites, or null when the caller has no personal favorites scope.

created_timestring date-time

Date and time when this agent was created.

last_edited_timestring date-time

Date and time when this agent was last edited.

instructionsstring nullable

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

Example response

{
  "icon": {
    "emoji": "😀"
  }
}

Changes

  • 789bd1e5766bRevision changes
    • warning

      added the new owner_allowance_limit enum value to the / response property for the response status

  • 61fced3986b8Revision changes
    • warning

      added the new shopify enum value to the /// response property for the response status