Notion: Get agent
Notion agents.getAgent: arguments, response, policy and SDK examples.
← Agents operations · Get started
Operation notion.get_agent
Provider route: GET /v1/agents/{agent_id}. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/notion with npm, or alter-sdk-notion with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { NotionIntegration } from "@alter-ai/notion";
async function execute(input: Parameters<NotionIntegration["agents"]["getAgent"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new NotionIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.agents.getAgent(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_notion import NotionIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = NotionIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.agents.get_agent(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.agent_id | JSON | Required within parent | The agent ID (a UUID), or `notion_ai` for the personal agent. Endpoint-specific restrictions still apply. |
path.agent_id (anyOf 1) | string | Alternative | |
path.agent_id (anyOf 2) | string | Alternative | Always `notion_ai` Must equal: notion_ai |
query | object | Optional | Additional keys: not allowed |
query.verbose | boolean | Optional | Whether to include the agent’s inline instructions. Defaults to false. |
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
agent_type | string | Required within parent | 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. Known values: notion_ai, custom_agent, autofill_custom_agent, external |
agent_version | JSON | Required within parent | |
agent_version (anyOf 1) | object | Alternative | Additional keys: allowed |
agent_version (anyOf 1).id | string | Required within parent | The ID of the published artifact. Format: uuid |
agent_version (anyOf 1).number | JSON | Required within parent | |
agent_version (anyOf 1).number (anyOf 1) | number | Alternative | The version number. |
agent_version (anyOf 1).number (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
agent_version (anyOf 1).published_at | string | Required within parent | The ISO 8601 timestamp when this version was published. |
agent_version (anyOf 2) | null | Alternative | |
connections | array | Required within parent | Integrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions. Maximum items: 100 |
connections[] | JSON | Each item | |
connections[] (anyOf 1) | Model | Alternative | Expand Get agent — response body — connections item type notion |
connections[] (anyOf 2) | Model | Alternative | Expand Get agent — response body — connections item type slack |
connections[] (anyOf 3) | Model | Alternative | Expand Get agent — response body — connections item type discord |
connections[] (anyOf 4) | Model | Alternative | Expand Get agent — response body — connections item type mcp server |
connections[] (anyOf 5) | Model | Alternative | Expand Get agent — response body — connections item type custom mcp server |
connections[] (anyOf 6) | Model | Alternative | Expand Get agent — response body — connections item account, name, permissions, type |
created_by | JSON | Required within parent | |
created_by (anyOf 1) | object | Alternative | Additional keys: allowed |
created_by (anyOf 1).id | string | Required within parent | The ID of the user that created this agent. Format: uuid |
created_by (anyOf 1).object | string | Required within parent | Always `user` Must equal: user |
created_by (anyOf 1).type | string | Required within parent | Always `user` Must equal: user |
created_by (anyOf 2) | null | Alternative | |
created_time | string | Optional | Date and time when this agent was created. Format: date-time |
credit_limit | JSON | Required within parent | 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. |
credit_limit (anyOf 1) | JSON | Alternative | |
credit_limit (anyOf 1) (anyOf 1) | integer | Alternative | Minimum: 0 |
credit_limit (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
credit_limit (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
credit_limit (anyOf 3) | null | Alternative | |
description | JSON | Required within parent | |
description (anyOf 1) | string | Alternative | |
description (anyOf 2) | null | Alternative | |
has_unpublished_changes | JSON | Required within parent | Whether the draft has edits not yet in the published version, or “hidden” when the caller lacks edit access to the agent. |
has_unpublished_changes (anyOf 1) | boolean | Alternative | |
has_unpublished_changes (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
icon | JSON | Required within parent | |
icon (anyOf 1) | Model | Alternative | Expand Get agent — response body — icon value |
icon (anyOf 2) | Model | Alternative | Expand Get agent — response body — icon type custom agent avatar |
icon (anyOf 3) | null | Alternative | |
id | JSON | Required within parent | |
id (anyOf 1) | string | Alternative | Format: uuid |
id (anyOf 2) | string | Alternative | Always `notion_ai` Must equal: notion_ai |
instructions | JSON | Optional | The agent’s inline instructions when verbose=true, or null when its instructions are stored on a page. |
instructions (anyOf 1) | string | Alternative | |
instructions (anyOf 2) | null | Alternative | |
instructions_page_id | JSON | Required within parent | |
instructions_page_id (anyOf 1) | string | Alternative | Format: uuid |
instructions_page_id (anyOf 2) | null | Alternative | |
is_favorited | JSON | Required within parent | Whether this agent is in the caller’s personal favorites, or null when the caller has no personal favorites scope. |
is_favorited (anyOf 1) | boolean | Alternative | |
is_favorited (anyOf 2) | null | Alternative | |
last_edited_time | string | Optional | Date and time when this agent was last edited. Format: date-time |
last_run_at | JSON | Required within parent | 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 (anyOf 1) | string | Alternative | Format: date-time Pattern: ^\d{4}-\d{2}-\d{2}T |
last_run_at (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
last_run_at (anyOf 3) | null | Alternative | |
last_run_time | JSON | Required within parent | 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_time (anyOf 1) | string | Alternative | Format: date-time Pattern: ^\d{4}-\d{2}-\d{2}T |
last_run_time (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
last_run_time (anyOf 3) | null | Alternative | |
model | JSON | Required within parent | The model the agent runs on: auto (Notion selects) or a pinned model. |
model (anyOf 1) | object | Alternative | Additional keys: allowed |
model (anyOf 1).mode | string | Required within parent | Always `auto` Must equal: auto |
model (anyOf 2) | object | Alternative | Additional keys: allowed |
model (anyOf 2).id | JSON | Required within parent | The public model this agent maps to (e.g. “claude-sonnet-5”), or null for a pre-release / early-access model. |
model (anyOf 2).id (anyOf 1) | string | Alternative | |
model (anyOf 2).id (anyOf 2) | null | Alternative | |
model (anyOf 2).mode | string | Required within parent | Always `pinned` Must equal: pinned |
name | string | Required within parent | |
object | string | Required within parent | Always `agent` Must equal: agent |
pause_reason | JSON | Required within parent | Why the agent is paused when status is “disabled” (e.g. “credit_limit”, “disabled_from_workspace_settings”); null when active. |
pause_reason (anyOf 1) | string | Alternative | 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` Known values: 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 |
pause_reason (anyOf 2) | null | Alternative | |
status | string | Required within parent | ”active” when the agent can run; “disabled” when it is paused (see pause_reason); “deleted” when it has been removed. Known values: active, disabled, deleted |
triggers | array | Required within parent | The agent’s configured triggers, each with a machine type, an enabled flag, and (for recurrence triggers) a structured schedule. Maximum items: 100 |
triggers[] | Model | Each item | Expand Get agent — response body — triggers item |
version | JSON | Required within parent | |
version (anyOf 1) | object | Alternative | Additional keys: allowed |
version (anyOf 1).id | string | Required within parent | The ID of the published artifact. Format: uuid |
version (anyOf 1).number | JSON | Required within parent | |
version (anyOf 1).number (anyOf 1) | number | Alternative | The version number. |
version (anyOf 1).number (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
version (anyOf 1).published_at | string | Required within parent | The ISO 8601 timestamp when this version was published. |
version (anyOf 2) | null | Alternative |
Referenced models: Get agent — response body — icon value, Get agent — response body — connections item type slack, Get agent — response body — connections item account, name, permissions, type, Get agent — response body — connections item type discord, Get agent — response body — connections item type mcp server, Get agent — response body — connections item type notion, Get agent — response body — connections item type custom mcp server, Get agent — response body — icon type custom agent avatar, Get agent — response body — triggers item
Schemas
Section titled “Schemas”13 more schemas are linked from the tables above, on the schema pages.
Get agent — response body — icon value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Get agent — response body — icon value Emoji |
$ (anyOf 2) | Model | Alternative | Expand Get agent — response body — icon value File |
$ (anyOf 3) | Model | Alternative | Expand Get agent — response body — icon value External |
$ (anyOf 4) | Model | Alternative | Expand Get agent — response body — icon value Custom Emoji |
$ (anyOf 5) | Model | Alternative | Expand Get agent — response body — icon value Icon |
Referenced models: Get agent — response body — icon value Custom Emoji, Get agent — response body — icon value Emoji, Get agent — response body — icon value External, Get agent — response body — icon value File, Get agent — response body — icon value Icon
Get agent — response body — connections item type slack
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
account | JSON | Required within parent | The linked Slack workspace, null when none is linked, or "hidden" when the caller lacks edit access to the agent. |
account (anyOf 1) | object | Alternative | Additional keys: allowed |
account (anyOf 1).team_id | string | Required within parent | |
account (anyOf 1).type | string | Required within parent | Always `slack_workspace` Must equal: slack_workspace |
account (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
account (anyOf 3) | null | Alternative | |
name | string | Required within parent | |
permissions | array | Required within parent | Maximum items: 100 |
permissions[] | Model | Each item | Expand Get agent — response body — connections item type slack permissions item |
type | string | Required within parent | Always `slack` Must equal: slack |
Referenced models: Get agent — response body — connections item type slack permissions item
Get agent — response body — connections item account, name, permissions, type
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
account | JSON | Required within parent | The provider-side account identifier, null when none is linked, or "hidden" when the caller lacks edit access to the agent. |
account (anyOf 1) | string | Alternative | |
account (anyOf 2) | null | Alternative | |
name | string | Required within parent | |
permissions | array | Required within parent | Maximum items: 100 |
permissions[] | object | Each item | Additional keys: allowed |
permissions[].scopes | array | Required within parent | The scopes granted on this target. Maximum items: 100 |
permissions[].scopes[] | string | Each item | |
permissions[].target | object | Required within parent | Additional keys: allowed |
permissions[].target.id | string | Required within parent | |
permissions[].target.type | string | Required within parent | |
type | string | Required within parent | The connector's machine name (e.g. "github", "google_drive"). Known values: asana, box, calendar, computer, confluence, cursor, feedback, files, fs, github, gmail, google_calendar, google_drive, google_drive_oauth, gtm, helpdocs, images, jira, linear, mail, marketplace, memory, microsoft_teams, microsoft_teams_oauth, outlook, salesforce, search, security, sharepoint, sharepoint_oauth, shopify, skills, system, test, web, webhooks, worker, workers |
Get agent — response body — connections item type discord
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
account | JSON | Required within parent | The linked Discord server, null when none is linked, or "hidden" when the caller lacks edit access to the agent. |
account (anyOf 1) | object | Alternative | Additional keys: allowed |
account (anyOf 1).id | string | Required within parent | |
account (anyOf 1).type | string | Required within parent | Always `discord_server` Must equal: discord_server |
account (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
account (anyOf 3) | null | Alternative | |
name | string | Required within parent | |
permissions | array | Required within parent | Maximum items: 100 |
permissions[] | Model | Each item | Expand Get agent — response body — connections item type discord permissions item |
type | string | Required within parent | Always `discord` Must equal: discord |
Referenced models: Get agent — response body — connections item type discord permissions item
Get agent — response body — connections item type mcp server
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
account | JSON | Required within parent | The MCP server host, null when none is linked, or "hidden" when the caller lacks edit access to the agent. |
account (anyOf 1) | object | Alternative | Additional keys: allowed |
account (anyOf 1).server_host | string | Required within parent | The MCP server host (never the full URL, which can carry credentials or private path components). |
account (anyOf 1).type | string | Required within parent | Always `mcp_server` Must equal: mcp_server |
account (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
account (anyOf 3) | null | Alternative | |
enabled_tools | JSON | Required within parent | 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. |
enabled_tools (anyOf 1) | array | Alternative | Maximum items: 100 |
enabled_tools (anyOf 1)[] | object | Each item | Additional keys: allowed |
enabled_tools (anyOf 1)[].name | string | Required within parent | |
enabled_tools (anyOf 1)[].title | JSON | Required within parent | |
enabled_tools (anyOf 1)[].title (anyOf 1) | string | Alternative | |
enabled_tools (anyOf 1)[].title (anyOf 2) | null | Alternative | |
enabled_tools (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
enabled_tools (anyOf 3) | null | Alternative | |
name | string | Required within parent | |
run_tools_automatically | object | Required within parent | Whether read / write tool calls run without a confirmation step. Additional keys: allowed |
run_tools_automatically.read | boolean | Required within parent | Whether read tool calls run without a confirmation step. |
run_tools_automatically.write | boolean | Required within parent | Whether write tool calls run without a confirmation step. |
type | string | Required within parent | Always `mcp_server` Must equal: mcp_server |
Get agent — response body — connections item type notion
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
account | null | Required within parent | |
name | string | Required within parent | |
permissions | array | Required within parent | Maximum items: 100 |
permissions[] | Model | Each item | Expand Get agent — response body — connections item type notion permissions item |
type | string | Required within parent | Always `notion` Must equal: notion |
Referenced models: Get agent — response body — connections item type notion permissions item
Get agent — response body — icon type custom agent avatar
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
custom_agent_avatar | object | Required within parent | The static and animated URLs for the agent avatar. Additional keys: allowed |
custom_agent_avatar.animated_url | string | Required within parent | The URL of the animated custom agent avatar. |
custom_agent_avatar.static_url | string | Required within parent | The URL of the static custom agent avatar. |
type | string | Required within parent | Type of icon. In this case, a custom agent avatar. Must equal: custom_agent_avatar |
Get agent — response body — triggers item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
config | object | Optional | Remaining per-type trigger configuration (e.g. watched channel ids, reaction config), keys in snake_case. Present only when the trigger carries such state. Additional keys: see wildcard field |
config.* | JSON | Additional keys | |
enabled | boolean | Required within parent | Whether this trigger is currently enabled. |
schedule | Model | Optional | Expand Get agent — response body — triggers item schedule |
type | string | Required within parent | Machine trigger type (e.g. "notion.agent.mentioned", "recurrence", "slack.reaction.added"). |
Referenced models: Get agent — response body — triggers item schedule
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: notion.get_agent. Catalog operation: get_agent. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Pinned headers: {"Notion-Version": "2026-03-11"}