> ## Documentation Index > Fetch the complete documentation index at: https://developers.notion.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve an agent > Retrieve metadata for one accessible Custom Agent. ## OpenAPI ````yaml get /v1/agents/{agent_id} openapi: 3.1.0 info: title: Notion API version: 1.0.0 termsOfService: >- https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac servers: - url: https://api.notion.com security: - bearerAuth: [] tags: - name: Databases description: Database endpoints - name: Data sources description: Data source endpoints - name: Pages description: Page endpoints - name: Async tasks description: Async task endpoints - name: Blocks description: Block endpoints - name: Comments description: Comment endpoints - name: File uploads description: File upload endpoints - name: OAuth description: OAuth endpoints (basic authentication) - name: Users description: User endpoints - name: Search description: Search endpoints - name: Views description: View endpoints - name: Agents description: Agent endpoints - name: Sessions description: Session endpoints - name: Custom emojis description: Custom emoji endpoints - name: Meeting notes description: Meeting notes endpoints paths: /v1/agents/{agent_id}: get: tags: - Agents summary: Get agent operationId: get-agent parameters: - name: agent_id in: path required: true schema: oneOf: - $ref: '#/components/schemas/idRequest' - type: string enum: - notion_ai - 33333333-3333-3333-3333-333333333333 description: 'One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`' description: >- The agent ID (a UUID), or `notion_ai` for the personal agent. Endpoint-specific restrictions still apply. - name: verbose in: query schema: type: boolean description: >- Whether to include the agent's inline instructions. Defaults to false. - $ref: '#/components/parameters/notionVersion' responses: '200': description: '' content: application/json: schema: type: object properties: object: type: string const: agent description: Always `agent` id: anyOf: - $ref: '#/components/schemas/idResponse' - type: string const: notion_ai description: Always `notion_ai` agent_type: type: string enum: - notion_ai - custom_agent - autofill_custom_agent - external description: >- 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. name: type: string description: oneOf: - type: string - type: 'null' instructions_page_id: oneOf: - $ref: '#/components/schemas/idResponse' - type: 'null' icon: oneOf: - $ref: '#/components/schemas/pageIconResponse' - type: object properties: type: type: string const: custom_agent_avatar description: Type of icon. In this case, a custom agent avatar. custom_agent_avatar: type: object properties: static_url: type: string description: The URL of the static custom agent avatar. animated_url: type: string description: The URL of the animated custom agent avatar. additionalProperties: false required: - static_url - animated_url description: The static and animated URLs for the agent avatar. additionalProperties: false required: - type - custom_agent_avatar - type: 'null' model: oneOf: - type: object properties: mode: type: string const: auto description: Always `auto` additionalProperties: false required: - mode - type: object properties: mode: type: string const: pinned description: Always `pinned` id: oneOf: - type: string - type: 'null' description: >- The public model this agent maps to (e.g. "claude-sonnet-5"), or null for a pre-release / early-access model. additionalProperties: false required: - mode - id description: >- The model the agent runs on: auto (Notion selects) or a pinned model. connections: type: array items: oneOf: - type: object properties: type: type: string const: notion description: Always `notion` name: type: string account: type: 'null' permissions: type: array items: type: object properties: target: oneOf: - type: object properties: type: type: string const: page description: Always `page` id: type: string additionalProperties: false required: - type - id - type: object properties: type: type: string const: database_property description: Always `database_property` data_source_id: type: string property_id: type: string additionalProperties: false required: - type - data_source_id - property_id - type: object properties: type: type: string const: agent description: Always `agent` id: type: string additionalProperties: false required: - type - id - type: object properties: type: type: string const: workspace description: Always `workspace` additionalProperties: false required: - type - type: object properties: type: type: string const: owner_private_pages description: Always `owner_private_pages` additionalProperties: false required: - type - type: object properties: type: type: string const: web_search description: Always `web_search` allowed_domains: oneOf: - type: array items: type: string maxItems: 100 - type: 'null' description: >- Domains web search is restricted to, or null when unrestricted. additionalProperties: false required: - type - allowed_domains - type: object properties: type: type: string const: notion_help_docs_search description: Always `notion_help_docs_search` additionalProperties: false required: - type scopes: type: array items: type: string maxItems: 100 description: >- Content roles ("reader" | "comment_only" | "read_and_write" | "editor") for scoped targets, or search verbs ("allow" | "disallow") for the search targets. additionalProperties: false required: - target - scopes maxItems: 100 additionalProperties: false required: - type - name - account - permissions - type: object properties: type: type: string const: slack description: Always `slack` name: type: string account: oneOf: - type: object properties: type: type: string const: slack_workspace description: Always `slack_workspace` team_id: type: string additionalProperties: false required: - type - team_id - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The linked Slack workspace, null when none is linked, or "hidden" when the caller lacks edit access to the agent. permissions: type: array items: type: object properties: target: oneOf: - type: object properties: type: type: string const: slack_channel description: Always `slack_channel` id: type: string additionalProperties: false required: - type - id - type: object properties: type: type: string const: slack_all_public_channels description: Always `slack_all_public_channels` additionalProperties: false required: - type - type: object properties: type: type: string const: slack_all_channels description: Always `slack_all_channels` additionalProperties: false required: - type scopes: type: array items: type: string maxItems: 100 description: >- Slack verbs granted on this target ("read" | "write" | "reply_in_thread" | "react"). additionalProperties: false required: - target - scopes maxItems: 100 additionalProperties: false required: - type - name - account - permissions - type: object properties: type: type: string const: discord description: Always `discord` name: type: string account: oneOf: - type: object properties: type: type: string const: discord_server description: Always `discord_server` id: type: string additionalProperties: false required: - type - id - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The linked Discord server, null when none is linked, or "hidden" when the caller lacks edit access to the agent. permissions: type: array items: type: object properties: target: oneOf: - type: object properties: type: type: string const: discord_channel description: Always `discord_channel` id: type: string additionalProperties: false required: - type - id - type: object properties: type: type: string const: discord_all_channels description: Always `discord_all_channels` additionalProperties: false required: - type scopes: type: array items: type: string maxItems: 100 description: >- Discord verbs granted on this target ("read" | "write" | "reply_in_thread" | "react"). additionalProperties: false required: - target - scopes maxItems: 100 additionalProperties: false required: - type - name - account - permissions - type: object properties: type: type: string const: mcp_server description: Always `mcp_server` name: type: string account: oneOf: - type: object properties: type: type: string const: mcp_server description: Always `mcp_server` server_host: type: string description: >- The MCP server host (never the full URL, which can carry credentials or private path components). additionalProperties: false required: - type - server_host - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The MCP server host, null when none is linked, or "hidden" when the caller lacks edit access to the agent. enabled_tools: oneOf: - type: array items: type: object properties: name: type: string title: oneOf: - type: string - type: 'null' additionalProperties: false required: - name - title maxItems: 100 - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The tools the agent may call, null when all tools are enabled (including any the server adds later), or "hidden" when the caller lacks edit access to the agent. run_tools_automatically: type: object properties: read: type: boolean description: >- Whether read tool calls run without a confirmation step. write: type: boolean description: >- Whether write tool calls run without a confirmation step. additionalProperties: false required: - read - write description: >- Whether read / write tool calls run without a confirmation step. additionalProperties: false required: - type - name - account - enabled_tools - run_tools_automatically - type: object properties: type: type: string const: custom_mcp_server description: Always `custom_mcp_server` name: type: string account: oneOf: - type: object properties: type: type: string const: mcp_server description: Always `mcp_server` server_host: type: string description: >- The MCP server host (never the full URL, which can carry credentials or private path components). additionalProperties: false required: - type - server_host - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The MCP server host, null when none is linked, or "hidden" when the caller lacks edit access to the agent. enabled_tools: oneOf: - type: array items: type: object properties: name: type: string title: oneOf: - type: string - type: 'null' additionalProperties: false required: - name - title maxItems: 100 - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The tools the agent may call, null when all tools are enabled (including any the server adds later), or "hidden" when the caller lacks edit access to the agent. run_tools_automatically: type: object properties: read: type: boolean description: >- Whether read tool calls run without a confirmation step. write: type: boolean description: >- Whether write tool calls run without a confirmation step. additionalProperties: false required: - read - write description: >- Whether read / write tool calls run without a confirmation step. additionalProperties: false required: - type - name - account - enabled_tools - run_tools_automatically - type: object properties: type: type: string enum: - asana - box - browser - calendar - computer - confluence - cursor - files - fs - github - gmail - google_calendar - google_drive - google_drive_oauth - gtm - helpdocs - images - jira - linear - mail - marketplace - memory - microsoft_teams - outlook - salesforce - search - security - sharepoint - skills - system - test - web - webhooks - worker - workers description: >- The connector's machine name (e.g. "github", "google_drive"). name: type: string account: oneOf: - type: string - type: 'null' description: >- The provider-side account identifier, null when none is linked, or "hidden" when the caller lacks edit access to the agent. permissions: type: array items: type: object properties: target: type: object properties: type: type: string id: type: string additionalProperties: false required: - type - id scopes: type: array items: type: string maxItems: 100 description: The scopes granted on this target. additionalProperties: false required: - target - scopes maxItems: 100 additionalProperties: false required: - type - name - account - permissions maxItems: 100 description: >- Integrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions. status: type: string enum: - active - disabled - deleted description: >- "active" when the agent can run; "disabled" when it is paused (see pause_reason); "deleted" when it has been removed. pause_reason: oneOf: - type: string enum: - 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 description: >- One of: `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` - type: 'null' description: >- Why the agent is paused when status is "disabled" (e.g. "credit_limit", "disabled_from_workspace_settings"); null when active. created_by: oneOf: - type: object properties: object: type: string const: user description: Always `user` type: type: string const: user description: Always `user` id: $ref: '#/components/schemas/idResponse' description: The ID of the user that created this agent. additionalProperties: false required: - object - type - id - type: 'null' version: oneOf: - type: object properties: id: $ref: '#/components/schemas/idResponse' description: The ID of the published artifact. number: type: number description: The version number. published_at: type: string description: >- The ISO 8601 timestamp when this version was published. additionalProperties: false required: - id - number - published_at - type: 'null' agent_version: oneOf: - type: object properties: id: $ref: '#/components/schemas/idResponse' description: The ID of the published artifact. number: type: number description: The version number. published_at: type: string description: >- The ISO 8601 timestamp when this version was published. additionalProperties: false required: - id - number - published_at - type: 'null' has_unpublished_changes: oneOf: - type: boolean - type: string const: hidden description: Always `hidden` description: >- 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: oneOf: - type: string format: date-time pattern: ^\d{4}-\d{2}-\d{2}T - type: string const: hidden description: Always `hidden` - type: 'null' description: >- 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. last_run_at: oneOf: - type: string format: date-time pattern: ^\d{4}-\d{2}-\d{2}T - type: string const: hidden description: Always `hidden` - type: 'null' description: >- 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. credit_limit: oneOf: - type: integer minimum: 0 - type: string const: hidden description: Always `hidden` - type: 'null' description: >- 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. triggers: type: array items: type: object properties: type: type: string description: >- Machine trigger type (e.g. "notion.agent.mentioned", "recurrence", "slack.reaction.added"). enabled: type: boolean description: Whether this trigger is currently enabled. schedule: type: object properties: frequency: type: string description: >- Base cadence unit ("hour" | "day" | "week" | "month" | "year"). interval: type: integer minimum: 1 description: >- Multiplier on the frequency (e.g. every 2 weeks). weekdays: type: array items: type: string maxItems: 100 description: >- Days of the week the schedule runs (e.g. "monday"). Present for weekly cadences and monthly weekday restrictions. monthdays: type: array items: type: integer minimum: 1 maxItems: 100 description: >- Days of the month the schedule runs. Present for monthly monthday restrictions. week_numbers: type: array items: type: integer maxItems: 100 description: >- Week-of-month ordinals for a monthly weekday restriction (e.g. [2, 3] for the 2nd and 3rd occurrence); -1 means the last week. hour: type: integer minimum: 0 description: Hour of day (0–23) the schedule runs. minute: type: integer minimum: 0 description: Minute of the hour (0–59) the schedule runs. timezone: type: string description: IANA timezone (e.g. "America/New_York"). start_date: type: string description: ISO 8601 timestamp the schedule starts from. end: oneOf: - type: object properties: type: type: string const: date description: Always `date` end_at: type: string description: >- ISO 8601 timestamp when the schedule stops. additionalProperties: false required: - type - end_at - type: object properties: type: type: string const: count description: Always `count` occurrences: type: integer minimum: 0 description: >- Number of occurrences after which the schedule stops. additionalProperties: false required: - type - occurrences description: When the schedule stops, when it is bounded. additionalProperties: false required: - frequency - interval description: >- Structured recurrence cadence. Present only for recurrence triggers. config: type: object additionalProperties: {} description: >- Remaining per-type trigger configuration (e.g. watched channel ids, reaction config), keys in snake_case. Present only when the trigger carries such state. additionalProperties: false required: - type - enabled maxItems: 100 description: >- The agent's configured triggers, each with a machine type, an enabled flag, and (for recurrence triggers) a structured schedule. created_time: type: string format: date-time description: Date and time when this agent was created. last_edited_time: type: string format: date-time description: Date and time when this agent was last edited. instructions: oneOf: - type: string - type: 'null' description: >- The agent's inline instructions when verbose=true, or null when its instructions are stored on a page. additionalProperties: false required: - object - id - agent_type - name - description - instructions_page_id - icon - model - connections - status - pause_reason - created_by - version - agent_version - has_unpublished_changes - last_run_time - last_run_at - credit_limit - triggers '400': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_400' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_401' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_403' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_404' '406': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_406' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_409' '429': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_429' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_500' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_503' '504': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_504' '529': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_529' x-codeSamples: - lang: javascript label: TypeScript SDK source: |- import { Client } from "@notionhq/client" const notion = new Client({ auth: process.env.NOTION_API_KEY }) const response = await notion.agents.retrieve({ agent_id: "1f0c7c06-781b-4987-9986-5c8dd3028013" }) components: schemas: idRequest: type: string idResponse: type: string format: uuid pageIconResponse: oneOf: - $ref: '#/components/schemas/emojiPageIconResponse' - $ref: '#/components/schemas/filePageIconResponse' - $ref: '#/components/schemas/externalPageIconResponse' - $ref: '#/components/schemas/customEmojiPageIconResponse' - $ref: '#/components/schemas/iconPageIconResponse' error_api_400: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - invalid_json - invalid_request_url - invalid_request - missing_version - invalid_beta - validation_error - invalid_credit_limit status: const: 400 required: - code - status additionalProperties: false error_api_401: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - unauthorized status: const: 401 required: - code - status additionalProperties: false error_api_403: oneOf: - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - restricted_resource - status_change_not_allowed status: const: 403 required: - code - status additionalProperties: false - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: const: workspace_credits_exhausted status: const: 403 additional_data: type: object properties: tool_error_code: const: workspace_credits_exhausted tool_error_class: const: entitlement_required tool_error_retryable: const: 'false' recovery_kind: enum: - contact_workspace_owner - open_workspace_credit_settings description: The recovery action selected by Notion for the caller. recovery_url: type: string format: uri description: >- Present when recovery_kind directs the caller to a settings page. required: - tool_error_code - tool_error_class - tool_error_retryable - recovery_kind additionalProperties: oneOf: - type: string - type: array items: type: string required: - code - status - additional_data - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: const: agent_credit_limit_reached status: const: 403 additional_data: type: object properties: tool_error_code: const: agent_credit_limit_reached tool_error_class: const: entitlement_required tool_error_retryable: const: 'false' recovery_kind: enum: - contact_workspace_owner - none - open_agent_settings - request_agent_limit_increase - request_pending description: The recovery action selected by Notion for the caller. recovery_url: type: string format: uri description: >- Present when recovery_kind directs the caller to a settings page. required: - tool_error_code - tool_error_class - tool_error_retryable - recovery_kind additionalProperties: oneOf: - type: string - type: array items: type: string required: - code - status - additional_data error_api_404: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - object_not_found - directory_not_found status: const: 404 required: - code - status additionalProperties: false error_api_406: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - row_limit_exceeded status: const: 406 required: - code - status additionalProperties: false error_api_409: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - conflict_error - idempotency_key_reused - agent_deleted status: const: 409 required: - code - status additionalProperties: false error_api_429: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - rate_limited status: const: 429 required: - code - status additionalProperties: false error_api_500: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - internal_server_error status: const: 500 required: - code - status additionalProperties: false error_api_503: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_unavailable status: const: 503 required: - code - status additionalProperties: false error_api_504: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - gateway_timeout status: const: 504 required: - code - status additionalProperties: false error_api_529: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_overload status: const: 529 required: - code - status additionalProperties: false emojiPageIconResponse: type: object properties: type: type: string const: emoji description: Type of icon. In this case, an emoji. emoji: $ref: '#/components/schemas/emojiRequest' description: The emoji character used as the icon. additionalProperties: false required: - type - emoji title: Emoji filePageIconResponse: type: object properties: type: type: string const: file description: Type of icon. In this case, a file. file: $ref: '#/components/schemas/internalFileResponse' description: The file URL for the icon. additionalProperties: false required: - type - file title: File externalPageIconResponse: type: object properties: type: type: string const: external description: Type of icon. In this case, an external URL. external: type: object properties: url: type: string description: The URL of the external file or resource. additionalProperties: false required: - url description: The external URL for the icon. additionalProperties: false required: - type - external title: External customEmojiPageIconResponse: type: object properties: type: type: string const: custom_emoji description: Type of icon. In this case, a custom emoji. custom_emoji: $ref: '#/components/schemas/customEmojiResponse' description: The custom emoji details for the icon. additionalProperties: false required: - type - custom_emoji title: Custom Emoji iconPageIconResponse: type: object properties: type: type: string const: icon description: Type of icon. In this case, a Notion native icon. icon: $ref: '#/components/schemas/noticonIconResponse' description: The Notion native icon, specified by name and color. additionalProperties: false required: - type - icon title: Icon publicApiCommonErrorResponse: type: object properties: object: const: error message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - message emojiRequest: type: string example: 😀 internalFileResponse: type: object properties: url: type: string description: The URL of the file. expiry_time: type: string format: date-time description: The time when the URL will expire. additionalProperties: false required: - url - expiry_time customEmojiResponse: type: object properties: id: $ref: '#/components/schemas/idResponse' description: The ID of the custom emoji. name: type: string description: The name of the custom emoji. url: type: string description: The URL of the custom emoji. additionalProperties: false required: - id - name - url noticonIconResponse: type: object properties: name: $ref: '#/components/schemas/noticonName' description: >- The name of the Notion icon (e.g. pizza, meeting, home). See the Notion icon picker for valid names. color: $ref: '#/components/schemas/noticonColor' description: >- The color variant of the icon. Valid values: gray, lightgray, brown, yellow, orange, green, blue, purple, pink, red. additionalProperties: false required: - name - color noticonName: type: string examples: - pizza - meeting - home - star - robot noticonColor: type: string enum: - gray - lightgray - brown - yellow - orange - green - blue - purple - pink - red description: >- One of: `gray`, `lightgray`, `brown`, `yellow`, `orange`, `green`, `blue`, `purple`, `pink`, `red` parameters: notionVersion: name: Notion-Version in: header required: true schema: enum: - '2026-03-11' description: >- The [API version](/reference/versioning) to use for this request. The latest version is `2026-03-11`. securitySchemes: bearerAuth: type: http scheme: bearer ````