--- title: "Get agent" method: GET path: "/v1/agents/{agent_id}" tags: ["Agents"] --- # Get agent `GET /v1/agents/{agent_id}` ## Path parameters - `agent_id` union, required — The agent ID (a UUID), or `notion_ai` for the personal agent. Endpoint-specific restrictions still apply. - string - 'notion_ai' | '33333333-3333-3333-3333-333333333333' — One of: `notion_ai`, `33333333-3333-3333-3333-333333333333` ## Query parameters - `verbose` boolean — Whether to include the agent's inline instructions. Defaults to false. ## Headers - `Notion-Version` '2026-03-11', required ## Response `200` - object - `object` 'agent', required — Always `agent` - `id` union, required - string, uuid - 'notion_ai' — Always `notion_ai` - `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. - `name` string, required - `description` string, nullable, required - `instructions_page_id` string, uuid, required - `icon` union, required - union - EmojiPageIconResponse - `type` 'emoji', required — Type of icon. In this case, an emoji. - `emoji` string, required - FilePageIconResponse - `type` 'file', required — Type of icon. In this case, a file. - `file` InternalFileResponse, required - `url` string, required — The URL of the file. - `expiry_time` string, date-time, required — The time when the URL will expire. - ExternalPageIconResponse - `type` 'external', required — Type of icon. In this case, an external URL. - `external` object, required — The external URL for the icon. - `url` string, required — The URL of the external file or resource. - CustomEmojiPageIconResponse - `type` 'custom_emoji', required — Type of icon. In this case, a custom emoji. - `custom_emoji` CustomEmojiResponse, required - `id` string, uuid, required - `name` string, required — The name of the custom emoji. - `url` string, required — The URL of the custom emoji. - IconPageIconResponse - `type` 'icon', required — Type of icon. In this case, a Notion native icon. - `icon` NoticonIconResponse, required - `name` string, required - `color` 'gray' | 'lightgray' | 'brown' | 'yellow' | 'orange' | 'green' | 'blue' | 'purple' | 'pink' | 'red', required — One of: `gray`, `lightgray`, `brown`, `yellow`, `orange`, `green`, `blue`, `purple`, `pink`, `red` - object - `type` 'custom_agent_avatar', required — Type of icon. In this case, a custom agent avatar. - `custom_agent_avatar` object, required — The static and animated URLs for the agent avatar. - `static_url` string, required — The URL of the static custom agent avatar. - `animated_url` string, required — The URL of the animated custom agent avatar. - `model` union, required — The model the agent runs on: auto (Notion selects) or a pinned model. - object - `mode` 'auto', required — Always `auto` - object - `mode` 'pinned', required — Always `pinned` - `id` string, nullable, required — The public model this agent maps to (e.g. "claude-sonnet-5"), or null for a pre-release / early-access model. - `connections` union[], required — Integrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions. - union - object - `type` 'notion', required — Always `notion` - `name` string, required - `account` unknown, required - `permissions` object[], required - `target` union, required - object - … - object - … - object - … - object - … - object - … - object - … - object - … - `scopes` string[], required — Content roles ("reader" | "comment_only" | "read_and_write" | "editor") for scoped targets, or search verbs ("allow" | "disallow") for the search targets. - object - `type` 'slack', required — Always `slack` - `name` string, required - `account` union, required — The linked Slack workspace, null when none is linked, or "hidden" when the caller lacks edit access to the agent. - object - `type` 'slack_workspace', required — Always `slack_workspace` - `team_id` string, required - 'hidden' — Always `hidden` - `permissions` object[], required - `target` union, required - object - … - object - … - object - … - `scopes` string[], required — Slack verbs granted on this target ("read" | "write" | "reply_in_thread" | "react"). - object - `type` 'discord', required — Always `discord` - `name` string, required - `account` union, required — The linked Discord server, null when none is linked, or "hidden" when the caller lacks edit access to the agent. - object - `type` 'discord_server', required — Always `discord_server` - `id` string, required - 'hidden' — Always `hidden` - `permissions` object[], required - `target` union, required - object - … - object - … - `scopes` string[], required — Discord verbs granted on this target ("read" | "write" | "reply_in_thread" | "react"). - object - `type` 'mcp_server', required — Always `mcp_server` - `name` string, required - `account` union, required — The MCP server host, null when none is linked, or "hidden" when the caller lacks edit access to the agent. - object - `type` 'mcp_server', required — Always `mcp_server` - `server_host` string, required — The MCP server host (never the full URL, which can carry credentials or private path components). - 'hidden' — Always `hidden` - `enabled_tools` union, required — 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. - object[] - `name` string, required - `title` string, nullable, required - 'hidden' — Always `hidden` - `run_tools_automatically` object, required — Whether read / write tool calls run without a confirmation step. - `read` boolean, required — Whether read tool calls run without a confirmation step. - `write` boolean, required — Whether write tool calls run without a confirmation step. - object - `type` 'custom_mcp_server', required — Always `custom_mcp_server` - `name` string, required - `account` union, required — The MCP server host, null when none is linked, or "hidden" when the caller lacks edit access to the agent. - object - `type` 'mcp_server', required — Always `mcp_server` - `server_host` string, required — The MCP server host (never the full URL, which can carry credentials or private path components). - 'hidden' — Always `hidden` - `enabled_tools` union, required — 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. - object[] - `name` string, required - `title` string, nullable, required - 'hidden' — Always `hidden` - `run_tools_automatically` object, required — Whether read / write tool calls run without a confirmation step. - `read` boolean, required — Whether read tool calls run without a confirmation step. - `write` boolean, required — Whether write tool calls run without a confirmation step. - object - `type` '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', required — The connector's machine name (e.g. "github", "google_drive"). - `name` string, required - `account` string, nullable, required — The provider-side account identifier, null when none is linked, or "hidden" when the caller lacks edit access to the agent. - `permissions` object[], required - `target` object, required - `type` string, required - `id` string, required - `scopes` string[], required — The scopes granted on this target. - `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' | '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', nullable, required — 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` - `created_by` object, nullable, required - `object` 'user', required — Always `user` - `type` 'user', required — Always `user` - `id` string, uuid, required - `version` object, nullable, required - `id` string, uuid, required - `number` number, required — The version number. - `published_at` string, required — The ISO 8601 timestamp when this version was published. - `agent_version` object, nullable, required - `id` string, uuid, required - `number` number, required — The version number. - `published_at` string, required — The ISO 8601 timestamp when this version was published. - `has_unpublished_changes` union, required — Whether the draft has edits not yet in the published version, or "hidden" when the caller lacks edit access to the agent. - boolean - 'hidden' — Always `hidden` - `last_run_time` union, 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. - string, date-time - 'hidden' — Always `hidden` - `last_run_at` union, 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. - string, date-time - 'hidden' — Always `hidden` - `credit_limit` union, 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. - integer - 'hidden' — Always `hidden` - `triggers` object[], required — The agent's configured triggers, each with a machine type, an enabled flag, and (for recurrence triggers) a structured schedule. - `type` string, required — Machine trigger type (e.g. "notion.agent.mentioned", "recurrence", "slack.reaction.added"). - `enabled` boolean, required — Whether this trigger is currently enabled. - `schedule` object — Structured recurrence cadence. Present only for recurrence triggers. - `frequency` string, required — Base cadence unit ("hour" | "day" | "week" | "month" | "year"). - `interval` integer, required — Multiplier on the frequency (e.g. every 2 weeks). - `weekdays` string[] — Days of the week the schedule runs (e.g. "monday"). Present for weekly cadences and monthly weekday restrictions. - `monthdays` integer[] — Days of the month the schedule runs. Present for monthly monthday restrictions. - `week_numbers` integer[] — 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` integer — Hour of day (0–23) the schedule runs. - `minute` integer — Minute of the hour (0–59) the schedule runs. - `timezone` string — IANA timezone (e.g. "America/New_York"). - `start_date` string — ISO 8601 timestamp the schedule starts from. - `end` union — When the schedule stops, when it is bounded. - object - `type` 'date', required — Always `date` - `end_at` string, required — ISO 8601 timestamp when the schedule stops. - object - `type` 'count', required — Always `count` - `occurrences` integer, required — Number of occurrences after which the schedule stops. - `config` object — Remaining per-type trigger configuration (e.g. watched channel ids, reaction config), keys in snake_case. Present only when the trigger carries such state. - `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, nullable — The agent's inline instructions when verbose=true, or null when its instructions are stored on a page. ## Other responses - `400` - `401` - `403` - `404` - `406` - `409` - `429` - `500` - `503` - `504` - `529` --- [API](https://skmtc.net/notion/apis/notion-api.md) · [All operations](https://skmtc.net/notion/apis/notion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notion/notion-api/revisions/dee5763763b0/schema)