Notion: Query agents
Notion agents.queryAgents: arguments, response, policy and SDK examples.
← Agents operations · Get started
Operation notion.query_agents
Provider route: POST /v1/agents/query. 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"]["queryAgents"]>[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.queryAgents(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.query_agents(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
body | object | Required within parent | Additional keys: not allowed |
body.filter | JSON | Optional | Filter agents by public properties, optionally combined with and/or. |
body.filter (oneOf 1) | JSON | Alternative | |
body.filter (oneOf 1) (oneOf 1) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 1).id | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 1).id.equals | string | Required within parent | |
body.filter (oneOf 1) (oneOf 1).property | string | Required within parent | Must equal: id |
body.filter (oneOf 1) (oneOf 2) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 2).property | string | Required within parent | Must equal: agent_type |
body.filter (oneOf 1) (oneOf 2).string | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 2).string.equals | string | Required within parent | One of: notion_ai, custom_agent, autofill_custom_agent |
body.filter (oneOf 1) (oneOf 3) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 3).people | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 3).people.contains | string | Required within parent | |
body.filter (oneOf 1) (oneOf 3).property | string | Required within parent | Must equal: created_by |
body.filter (oneOf 1) (oneOf 4) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 4).date | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 4).date.after | string | Optional | Format: date-time |
body.filter (oneOf 1) (oneOf 4).date.before | string | Optional | Format: date-time |
body.filter (oneOf 1) (oneOf 4).property | string | Required within parent | Must equal: created_time |
body.filter (oneOf 1) (oneOf 5) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 5).checkbox | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 5).checkbox.equals | boolean | Required within parent | |
body.filter (oneOf 1) (oneOf 5).property | string | Required within parent | Must equal: favorited |
body.filter (oneOf 1) (oneOf 6) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 6).mcp_server | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 6).mcp_server.contains | string | Required within parent | |
body.filter (oneOf 1) (oneOf 6).property | string | Required within parent | Must equal: connections |
body.filter (oneOf 1) (oneOf 7) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 7).property | string | Required within parent | Must equal: status |
body.filter (oneOf 1) (oneOf 7).status | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 7).status.in | array | Required within parent | Minimum items: 1 |
body.filter (oneOf 1) (oneOf 7).status.in[] | string | Each item | One of: active, disabled, deleted |
body.filter (oneOf 1) (oneOf 8) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 8).property | string | Required within parent | Must equal: model_mode |
body.filter (oneOf 1) (oneOf 8).select | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 8).select.equals | string | Required within parent | One of: auto, pinned |
body.filter (oneOf 1) (oneOf 9) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 9).number | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 9).number.equals | integer | Required within parent | Minimum: 1 |
body.filter (oneOf 1) (oneOf 9).property | string | Required within parent | Must equal: agent_version |
body.filter (oneOf 1) (oneOf 10) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 10).date | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 1) (oneOf 10).date.after | string | Optional | Format: date-time |
body.filter (oneOf 1) (oneOf 10).date.before | string | Optional | Format: date-time |
body.filter (oneOf 1) (oneOf 10).property | string | Required within parent | Must equal: last_run_at |
body.filter (oneOf 2) | JSON | Alternative | |
body.filter (oneOf 2) (oneOf 1) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and | array | Required within parent | Minimum items: 1 |
body.filter (oneOf 2) (oneOf 1).and[] | JSON | Each item | |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) | JSON | Alternative | |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 1) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 1).id | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 1).id.equals | string | Required within parent | |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 1).property | string | Required within parent | Must equal: id |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 2) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 2).property | string | Required within parent | Must equal: agent_type |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 2).string | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 2).string.equals | string | Required within parent | One of: notion_ai, custom_agent, autofill_custom_agent |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 3) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 3).people | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 3).people.contains | string | Required within parent | |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 3).property | string | Required within parent | Must equal: created_by |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4).date | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4).date.after | string | Optional | Format: date-time |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4).date.before | string | Optional | Format: date-time |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4).property | string | Required within parent | Must equal: created_time |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 5) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 5).checkbox | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 5).checkbox.equals | boolean | Required within parent | |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 5).property | string | Required within parent | Must equal: favorited |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 6) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 6).mcp_server | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 6).mcp_server.contains | string | Required within parent | |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 6).property | string | Required within parent | Must equal: connections |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7).property | string | Required within parent | Must equal: status |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7).status | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7).status.in | array | Required within parent | Minimum items: 1 |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7).status.in[] | string | Each item | One of: active, disabled, deleted |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 8) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 8).property | string | Required within parent | Must equal: model_mode |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 8).select | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 8).select.equals | string | Required within parent | One of: auto, pinned |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 9) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 9).number | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 9).number.equals | integer | Required within parent | Minimum: 1 |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 9).property | string | Required within parent | Must equal: agent_version |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10).date | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10).date.after | string | Optional | Format: date-time |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10).date.before | string | Optional | Format: date-time |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10).property | string | Required within parent | Must equal: last_run_at |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 2) | JSON | Alternative | |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 2) (oneOf 1) | Model | Alternative | Expand Query agents — request body — body filter value or or item value and |
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 2) (oneOf 2) | Model | Alternative | Expand Query agents — request body — body filter value or or item value or |
body.filter (oneOf 2) (oneOf 2) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or | array | Required within parent | Minimum items: 1 |
body.filter (oneOf 2) (oneOf 2).or[] | JSON | Each item | |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) | JSON | Alternative | |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 1) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 1).id | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 1).id.equals | string | Required within parent | |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 1).property | string | Required within parent | Must equal: id |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 2) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 2).property | string | Required within parent | Must equal: agent_type |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 2).string | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 2).string.equals | string | Required within parent | One of: notion_ai, custom_agent, autofill_custom_agent |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 3) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 3).people | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 3).people.contains | string | Required within parent | |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 3).property | string | Required within parent | Must equal: created_by |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4).date | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4).date.after | string | Optional | Format: date-time |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4).date.before | string | Optional | Format: date-time |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4).property | string | Required within parent | Must equal: created_time |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 5) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 5).checkbox | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 5).checkbox.equals | boolean | Required within parent | |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 5).property | string | Required within parent | Must equal: favorited |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 6) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 6).mcp_server | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 6).mcp_server.contains | string | Required within parent | |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 6).property | string | Required within parent | Must equal: connections |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7).property | string | Required within parent | Must equal: status |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7).status | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7).status.in | array | Required within parent | Minimum items: 1 |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7).status.in[] | string | Each item | One of: active, disabled, deleted |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 8) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 8).property | string | Required within parent | Must equal: model_mode |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 8).select | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 8).select.equals | string | Required within parent | One of: auto, pinned |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 9) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 9).number | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 9).number.equals | integer | Required within parent | Minimum: 1 |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 9).property | string | Required within parent | Must equal: agent_version |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10) | object | Alternative | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10).date | object | Required within parent | Additional keys: not allowed |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10).date.after | string | Optional | Format: date-time |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10).date.before | string | Optional | Format: date-time |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10).property | string | Required within parent | Must equal: last_run_at |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 2) | JSON | Alternative | |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 2) (oneOf 1) | Model | Alternative | Expand Query agents — request body — body filter value or or item value and |
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 2) (oneOf 2) | Model | Alternative | Expand Query agents — request body — body filter value or or item value or |
body.include_deleted | boolean | Optional | Whether to include soft-deleted agents. Defaults to false. |
body.page_size | integer | Optional | Number of agents to return. Maximum: 100. Maximum: 100 Minimum: 1 |
body.query | string | Optional | Search agent names and descriptions using a case-insensitive substring match. |
body.sorts | array | Optional | Ordered sort precedence. Defaults to created_time descending. Maximum items: 2 Minimum items: 1 |
body.sorts[] | object | Each item | Additional keys: not allowed |
body.sorts[].direction | string | Required within parent | Sort direction. One of: ascending, descending |
body.sorts[].property | string | Required within parent | Timestamp used to sort agents. One of: created_time, last_run_at |
body.start_cursor | string | Optional | Opaque continuation cursor from the previous page. |
body.verbose | boolean | Optional | Whether to include inline instructions for each agent. Defaults to false. |
Referenced models: Query agents — request body — body filter value or or item value or, Query agents — request body — body filter value or or item value and
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 |
has_more | boolean | Required within parent | |
next_cursor | JSON | Required within parent | |
next_cursor (anyOf 1) | string | Alternative | |
next_cursor (anyOf 2) | null | Alternative | |
object | string | Required within parent | Always `list` Must equal: list |
results | array | Required within parent | Maximum items: 100 |
results[] | JSON | Each item | |
results[] (anyOf 1) | object | Alternative | Additional keys: allowed |
results[] (anyOf 1).agent_type | string | Required within parent | What kind of agent this is: “custom_agent” is a standalone agent you chat with; “autofill_custom_agent” fills a database property. Known values: custom_agent, autofill_custom_agent |
results[] (anyOf 1).agent_version | JSON | Required within parent | |
results[] (anyOf 1).agent_version (anyOf 1) | object | Alternative | Additional keys: allowed |
results[] (anyOf 1).agent_version (anyOf 1).id | string | Required within parent | The ID of the published artifact. Format: uuid |
results[] (anyOf 1).agent_version (anyOf 1).number | JSON | Required within parent | |
results[] (anyOf 1).agent_version (anyOf 1).number (anyOf 1) | number | Alternative | The version number. |
results[] (anyOf 1).agent_version (anyOf 1).number (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
results[] (anyOf 1).agent_version (anyOf 1).published_at | string | Required within parent | The ISO 8601 timestamp when this version was published. |
results[] (anyOf 1).agent_version (anyOf 2) | null | Alternative | |
results[] (anyOf 1).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 |
results[] (anyOf 1).connections[] | JSON | Each item | |
results[] (anyOf 1).connections[] (anyOf 1) | Model | Alternative | Expand Get agent — response body — connections item type notion |
results[] (anyOf 1).connections[] (anyOf 2) | Model | Alternative | Expand Get agent — response body — connections item type slack |
results[] (anyOf 1).connections[] (anyOf 3) | Model | Alternative | Expand Get agent — response body — connections item type discord |
results[] (anyOf 1).connections[] (anyOf 4) | Model | Alternative | Expand Get agent — response body — connections item type mcp server |
results[] (anyOf 1).connections[] (anyOf 5) | Model | Alternative | Expand Get agent — response body — connections item type custom mcp server |
results[] (anyOf 1).connections[] (anyOf 6) | Model | Alternative | Expand Get agent — response body — connections item account, name, permissions, type |
results[] (anyOf 1).created_by | JSON | Required within parent | |
results[] (anyOf 1).created_by (anyOf 1) | object | Alternative | Additional keys: allowed |
results[] (anyOf 1).created_by (anyOf 1).id | string | Required within parent | The ID of the user or bot that created this agent. Format: uuid |
results[] (anyOf 1).created_by (anyOf 1).type | string | Required within parent | One of: `user`, `bot` Known values: user, bot |
results[] (anyOf 1).created_by (anyOf 2) | null | Alternative | |
results[] (anyOf 1).created_time | string | Required within parent | Date and time when this agent was created. Format: date-time |
results[] (anyOf 1).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. |
results[] (anyOf 1).credit_limit (anyOf 1) | JSON | Alternative | |
results[] (anyOf 1).credit_limit (anyOf 1) (anyOf 1) | integer | Alternative | Minimum: 0 |
results[] (anyOf 1).credit_limit (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
results[] (anyOf 1).credit_limit (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
results[] (anyOf 1).credit_limit (anyOf 3) | null | Alternative | |
results[] (anyOf 1).description | JSON | Required within parent | |
results[] (anyOf 1).description (anyOf 1) | string | Alternative | |
results[] (anyOf 1).description (anyOf 2) | null | Alternative | |
results[] (anyOf 1).icon | JSON | Required within parent | |
results[] (anyOf 1).icon (anyOf 1) | Model | Alternative | Expand Get agent — response body — icon value |
results[] (anyOf 1).icon (anyOf 2) | Model | Alternative | Expand Get agent — response body — icon type custom agent avatar |
results[] (anyOf 1).icon (anyOf 3) | null | Alternative | |
results[] (anyOf 1).id | string | Required within parent | Format: uuid |
results[] (anyOf 1).instructions | JSON | Optional | The agent’s inline instructions when verbose=true, or null when its instructions are stored on a page. |
results[] (anyOf 1).instructions (anyOf 1) | string | Alternative | |
results[] (anyOf 1).instructions (anyOf 2) | null | Alternative | |
results[] (anyOf 1).instructions_page_id | JSON | Required within parent | |
results[] (anyOf 1).instructions_page_id (anyOf 1) | string | Alternative | Format: uuid |
results[] (anyOf 1).instructions_page_id (anyOf 2) | null | Alternative | |
results[] (anyOf 1).last_edited_time | string | Required within parent | Date and time when this agent was last edited. Format: date-time |
results[] (anyOf 1).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. |
results[] (anyOf 1).last_run_at (anyOf 1) | string | Alternative | Format: date-time Pattern: ^\d{4}-\d{2}-\d{2}T |
results[] (anyOf 1).last_run_at (anyOf 2) | string | Alternative | Always `hidden` Must equal: hidden |
results[] (anyOf 1).last_run_at (anyOf 3) | null | Alternative | |
results[] (anyOf 1).model | JSON | Required within parent | The model selection: automatic, or pinned to a public model ID. |
results[] (anyOf 1).model (anyOf 1) | object | Alternative | Additional keys: allowed |
results[] (anyOf 1).model (anyOf 1).mode | string | Required within parent | Always `auto` Must equal: auto |
results[] (anyOf 1).model (anyOf 2) | object | Alternative | Additional keys: allowed |
results[] (anyOf 1).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. |
results[] (anyOf 1).model (anyOf 2).id (anyOf 1) | string | Alternative | |
results[] (anyOf 1).model (anyOf 2).id (anyOf 2) | null | Alternative | |
results[] (anyOf 1).model (anyOf 2).mode | string | Required within parent | Always `pinned` Must equal: pinned |
results[] (anyOf 1).name | string | Required within parent | |
results[] (anyOf 1).object | string | Required within parent | Always `agent` Must equal: agent |
results[] (anyOf 1).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. |
results[] (anyOf 1).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 |
results[] (anyOf 1).pause_reason (anyOf 2) | null | Alternative | |
results[] (anyOf 1).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 |
results[] (anyOf 1).triggers | array | Required within parent | The agent’s configured triggers, each with a machine type, an enabled flag, and a structured recurrence schedule when applicable. Maximum items: 100 |
results[] (anyOf 1).triggers[] | Model | Each item | Expand Get agent — response body — triggers item |
results[] (anyOf 2) | object | Alternative | Additional keys: allowed |
results[] (anyOf 2).agent_type | string | Required within parent | Always `notion_ai` Must equal: notion_ai |
results[] (anyOf 2).agent_version | null | Required within parent | |
results[] (anyOf 2).connections | array | Required within parent | Maximum items: 100 |
results[] (anyOf 2).connections[] | JSON | Each item | |
results[] (anyOf 2).connections[] (anyOf 1) | Model | Alternative | Expand Get agent — response body — connections item type notion |
results[] (anyOf 2).connections[] (anyOf 2) | Model | Alternative | Expand Get agent — response body — connections item type slack |
results[] (anyOf 2).connections[] (anyOf 3) | Model | Alternative | Expand Get agent — response body — connections item type discord |
results[] (anyOf 2).connections[] (anyOf 4) | Model | Alternative | Expand Get agent — response body — connections item type mcp server |
results[] (anyOf 2).connections[] (anyOf 5) | Model | Alternative | Expand Get agent — response body — connections item type custom mcp server |
results[] (anyOf 2).connections[] (anyOf 6) | Model | Alternative | Expand Get agent — response body — connections item account, name, permissions, type |
results[] (anyOf 2).created_by | null | Required within parent | |
results[] (anyOf 2).created_time | null | Required within parent | |
results[] (anyOf 2).credit_limit | null | Required within parent | |
results[] (anyOf 2).description | null | Required within parent | |
results[] (anyOf 2).icon | JSON | Required within parent | |
results[] (anyOf 2).icon (anyOf 1) | Model | Alternative | Expand Get agent — response body — icon value |
results[] (anyOf 2).icon (anyOf 2) | Model | Alternative | Expand Get agent — response body — icon type custom agent avatar |
results[] (anyOf 2).id | string | Required within parent | Always `notion_ai` Must equal: notion_ai |
results[] (anyOf 2).instructions_page_id | null | Required within parent | |
results[] (anyOf 2).last_edited_time | null | Required within parent | |
results[] (anyOf 2).last_run_at | null | Required within parent | |
results[] (anyOf 2).model | JSON | Required within parent | |
results[] (anyOf 2).model (anyOf 1) | object | Alternative | Additional keys: allowed |
results[] (anyOf 2).model (anyOf 1).mode | string | Required within parent | Always `auto` Must equal: auto |
results[] (anyOf 2).model (anyOf 2) | object | Alternative | Additional keys: allowed |
results[] (anyOf 2).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. |
results[] (anyOf 2).model (anyOf 2).id (anyOf 1) | string | Alternative | |
results[] (anyOf 2).model (anyOf 2).id (anyOf 2) | null | Alternative | |
results[] (anyOf 2).model (anyOf 2).mode | string | Required within parent | Always `pinned` Must equal: pinned |
results[] (anyOf 2).name | string | Required within parent | |
results[] (anyOf 2).object | string | Required within parent | Always `agent` Must equal: agent |
results[] (anyOf 2).pause_reason | null | Required within parent | |
results[] (anyOf 2).status | string | Required within parent | Always `active` Must equal: active |
results[] (anyOf 2).triggers | array | Required within parent | Maximum items: 100 |
results[] (anyOf 2).triggers[] | Model | Each item | Expand Get agent — response body — triggers item |
type | string | Required within parent | Always `agent` Must equal: agent |
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”19 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
Query agents — request body — body filter value or or item value or
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
or | array | Required within parent | Minimum items: 1 |
or[] | JSON | Each item | |
or[] (oneOf 1) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 1).id | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 1).id.equals | string | Required within parent | |
or[] (oneOf 1).property | string | Required within parent | Must equal: id |
or[] (oneOf 2) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 2).property | string | Required within parent | Must equal: agent_type |
or[] (oneOf 2).string | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 2).string.equals | string | Required within parent | One of: notion_ai, custom_agent, autofill_custom_agent |
or[] (oneOf 3) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 3).people | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 3).people.contains | string | Required within parent | |
or[] (oneOf 3).property | string | Required within parent | Must equal: created_by |
or[] (oneOf 4) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 4).date | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 4).date.after | string | Optional | Format: date-time |
or[] (oneOf 4).date.before | string | Optional | Format: date-time |
or[] (oneOf 4).property | string | Required within parent | Must equal: created_time |
or[] (oneOf 5) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 5).checkbox | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 5).checkbox.equals | boolean | Required within parent | |
or[] (oneOf 5).property | string | Required within parent | Must equal: favorited |
or[] (oneOf 6) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 6).mcp_server | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 6).mcp_server.contains | string | Required within parent | |
or[] (oneOf 6).property | string | Required within parent | Must equal: connections |
or[] (oneOf 7) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 7).property | string | Required within parent | Must equal: status |
or[] (oneOf 7).status | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 7).status.in | array | Required within parent | Minimum items: 1 |
or[] (oneOf 7).status.in[] | string | Each item | One of: active, disabled, deleted |
or[] (oneOf 8) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 8).property | string | Required within parent | Must equal: model_mode |
or[] (oneOf 8).select | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 8).select.equals | string | Required within parent | One of: auto, pinned |
or[] (oneOf 9) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 9).number | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 9).number.equals | integer | Required within parent | Minimum: 1 |
or[] (oneOf 9).property | string | Required within parent | Must equal: agent_version |
or[] (oneOf 10) | object | Alternative | Additional keys: not allowed |
or[] (oneOf 10).date | object | Required within parent | Additional keys: not allowed |
or[] (oneOf 10).date.after | string | Optional | Format: date-time |
or[] (oneOf 10).date.before | string | Optional | Format: date-time |
or[] (oneOf 10).property | string | Required within parent | Must equal: last_run_at |
Query agents — request body — body filter value or or item value and
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
and | array | Required within parent | Minimum items: 1 |
and[] | JSON | Each item | |
and[] (oneOf 1) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 1).id | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 1).id.equals | string | Required within parent | |
and[] (oneOf 1).property | string | Required within parent | Must equal: id |
and[] (oneOf 2) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 2).property | string | Required within parent | Must equal: agent_type |
and[] (oneOf 2).string | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 2).string.equals | string | Required within parent | One of: notion_ai, custom_agent, autofill_custom_agent |
and[] (oneOf 3) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 3).people | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 3).people.contains | string | Required within parent | |
and[] (oneOf 3).property | string | Required within parent | Must equal: created_by |
and[] (oneOf 4) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 4).date | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 4).date.after | string | Optional | Format: date-time |
and[] (oneOf 4).date.before | string | Optional | Format: date-time |
and[] (oneOf 4).property | string | Required within parent | Must equal: created_time |
and[] (oneOf 5) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 5).checkbox | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 5).checkbox.equals | boolean | Required within parent | |
and[] (oneOf 5).property | string | Required within parent | Must equal: favorited |
and[] (oneOf 6) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 6).mcp_server | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 6).mcp_server.contains | string | Required within parent | |
and[] (oneOf 6).property | string | Required within parent | Must equal: connections |
and[] (oneOf 7) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 7).property | string | Required within parent | Must equal: status |
and[] (oneOf 7).status | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 7).status.in | array | Required within parent | Minimum items: 1 |
and[] (oneOf 7).status.in[] | string | Each item | One of: active, disabled, deleted |
and[] (oneOf 8) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 8).property | string | Required within parent | Must equal: model_mode |
and[] (oneOf 8).select | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 8).select.equals | string | Required within parent | One of: auto, pinned |
and[] (oneOf 9) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 9).number | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 9).number.equals | integer | Required within parent | Minimum: 1 |
and[] (oneOf 9).property | string | Required within parent | Must equal: agent_version |
and[] (oneOf 10) | object | Alternative | Additional keys: not allowed |
and[] (oneOf 10).date | object | Required within parent | Additional keys: not allowed |
and[] (oneOf 10).date.after | string | Optional | Format: date-time |
and[] (oneOf 10).date.before | string | Optional | Format: date-time |
and[] (oneOf 10).property | string | Required within parent | Must equal: last_run_at |
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
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: notion.query_agents. Catalog operation: query_agents. 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"}