Skip to content

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.

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 os
from alter_sdk import App
from 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()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
bodyobjectRequired within parentAdditional keys: not allowed
body.filterJSONOptionalFilter agents by public properties, optionally combined with and/or.
body.filter (oneOf 1)JSONAlternative
body.filter (oneOf 1) (oneOf 1)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 1).idobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 1).id.equalsstringRequired within parent
body.filter (oneOf 1) (oneOf 1).propertystringRequired within parentMust equal: id
body.filter (oneOf 1) (oneOf 2)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 2).propertystringRequired within parentMust equal: agent_type
body.filter (oneOf 1) (oneOf 2).stringobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 2).string.equalsstringRequired within parentOne of: notion_ai, custom_agent, autofill_custom_agent
body.filter (oneOf 1) (oneOf 3)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 3).peopleobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 3).people.containsstringRequired within parent
body.filter (oneOf 1) (oneOf 3).propertystringRequired within parentMust equal: created_by
body.filter (oneOf 1) (oneOf 4)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 4).dateobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 4).date.afterstringOptionalFormat: date-time
body.filter (oneOf 1) (oneOf 4).date.beforestringOptionalFormat: date-time
body.filter (oneOf 1) (oneOf 4).propertystringRequired within parentMust equal: created_time
body.filter (oneOf 1) (oneOf 5)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 5).checkboxobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 5).checkbox.equalsbooleanRequired within parent
body.filter (oneOf 1) (oneOf 5).propertystringRequired within parentMust equal: favorited
body.filter (oneOf 1) (oneOf 6)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 6).mcp_serverobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 6).mcp_server.containsstringRequired within parent
body.filter (oneOf 1) (oneOf 6).propertystringRequired within parentMust equal: connections
body.filter (oneOf 1) (oneOf 7)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 7).propertystringRequired within parentMust equal: status
body.filter (oneOf 1) (oneOf 7).statusobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 7).status.inarrayRequired within parentMinimum items: 1
body.filter (oneOf 1) (oneOf 7).status.in[]stringEach itemOne of: active, disabled, deleted
body.filter (oneOf 1) (oneOf 8)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 8).propertystringRequired within parentMust equal: model_mode
body.filter (oneOf 1) (oneOf 8).selectobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 8).select.equalsstringRequired within parentOne of: auto, pinned
body.filter (oneOf 1) (oneOf 9)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 9).numberobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 9).number.equalsintegerRequired within parentMinimum: 1
body.filter (oneOf 1) (oneOf 9).propertystringRequired within parentMust equal: agent_version
body.filter (oneOf 1) (oneOf 10)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 10).dateobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 1) (oneOf 10).date.afterstringOptionalFormat: date-time
body.filter (oneOf 1) (oneOf 10).date.beforestringOptionalFormat: date-time
body.filter (oneOf 1) (oneOf 10).propertystringRequired within parentMust equal: last_run_at
body.filter (oneOf 2)JSONAlternative
body.filter (oneOf 2) (oneOf 1)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).andarrayRequired within parentMinimum items: 1
body.filter (oneOf 2) (oneOf 1).and[]JSONEach item
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1)JSONAlternative
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 1)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 1).idobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 1).id.equalsstringRequired within parent
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 1).propertystringRequired within parentMust equal: id
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 2)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 2).propertystringRequired within parentMust equal: agent_type
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 2).stringobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 2).string.equalsstringRequired within parentOne of: notion_ai, custom_agent, autofill_custom_agent
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 3)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 3).peopleobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 3).people.containsstringRequired within parent
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 3).propertystringRequired within parentMust equal: created_by
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4).dateobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4).date.afterstringOptionalFormat: date-time
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4).date.beforestringOptionalFormat: date-time
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 4).propertystringRequired within parentMust equal: created_time
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 5)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 5).checkboxobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 5).checkbox.equalsbooleanRequired within parent
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 5).propertystringRequired within parentMust equal: favorited
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 6)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 6).mcp_serverobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 6).mcp_server.containsstringRequired within parent
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 6).propertystringRequired within parentMust equal: connections
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7).propertystringRequired within parentMust equal: status
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7).statusobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7).status.inarrayRequired within parentMinimum items: 1
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 7).status.in[]stringEach itemOne of: active, disabled, deleted
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 8)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 8).propertystringRequired within parentMust equal: model_mode
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 8).selectobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 8).select.equalsstringRequired within parentOne of: auto, pinned
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 9)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 9).numberobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 9).number.equalsintegerRequired within parentMinimum: 1
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 9).propertystringRequired within parentMust equal: agent_version
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10).dateobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10).date.afterstringOptionalFormat: date-time
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10).date.beforestringOptionalFormat: date-time
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 1) (oneOf 10).propertystringRequired within parentMust equal: last_run_at
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 2)JSONAlternative
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 2) (oneOf 1)ModelAlternativeExpand Query agents — request body — body filter value or or item value and
body.filter (oneOf 2) (oneOf 1).and[] (oneOf 2) (oneOf 2)ModelAlternativeExpand Query agents — request body — body filter value or or item value or
body.filter (oneOf 2) (oneOf 2)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).orarrayRequired within parentMinimum items: 1
body.filter (oneOf 2) (oneOf 2).or[]JSONEach item
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1)JSONAlternative
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 1)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 1).idobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 1).id.equalsstringRequired within parent
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 1).propertystringRequired within parentMust equal: id
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 2)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 2).propertystringRequired within parentMust equal: agent_type
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 2).stringobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 2).string.equalsstringRequired within parentOne of: notion_ai, custom_agent, autofill_custom_agent
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 3)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 3).peopleobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 3).people.containsstringRequired within parent
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 3).propertystringRequired within parentMust equal: created_by
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4).dateobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4).date.afterstringOptionalFormat: date-time
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4).date.beforestringOptionalFormat: date-time
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 4).propertystringRequired within parentMust equal: created_time
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 5)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 5).checkboxobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 5).checkbox.equalsbooleanRequired within parent
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 5).propertystringRequired within parentMust equal: favorited
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 6)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 6).mcp_serverobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 6).mcp_server.containsstringRequired within parent
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 6).propertystringRequired within parentMust equal: connections
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7).propertystringRequired within parentMust equal: status
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7).statusobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7).status.inarrayRequired within parentMinimum items: 1
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 7).status.in[]stringEach itemOne of: active, disabled, deleted
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 8)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 8).propertystringRequired within parentMust equal: model_mode
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 8).selectobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 8).select.equalsstringRequired within parentOne of: auto, pinned
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 9)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 9).numberobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 9).number.equalsintegerRequired within parentMinimum: 1
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 9).propertystringRequired within parentMust equal: agent_version
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10)objectAlternativeAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10).dateobjectRequired within parentAdditional keys: not allowed
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10).date.afterstringOptionalFormat: date-time
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10).date.beforestringOptionalFormat: date-time
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 1) (oneOf 10).propertystringRequired within parentMust equal: last_run_at
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 2)JSONAlternative
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 2) (oneOf 1)ModelAlternativeExpand Query agents — request body — body filter value or or item value and
body.filter (oneOf 2) (oneOf 2).or[] (oneOf 2) (oneOf 2)ModelAlternativeExpand Query agents — request body — body filter value or or item value or
body.include_deletedbooleanOptionalWhether to include soft-deleted agents. Defaults to false.
body.page_sizeintegerOptionalNumber of agents to return. Maximum: 100.
Maximum: 100
Minimum: 1
body.querystringOptionalSearch agent names and descriptions using a case-insensitive substring match.
body.sortsarrayOptionalOrdered sort precedence. Defaults to created_time descending.
Maximum items: 2
Minimum items: 1
body.sorts[]objectEach itemAdditional keys: not allowed
body.sorts[].directionstringRequired within parentSort direction.
One of: ascending, descending
body.sorts[].propertystringRequired within parentTimestamp used to sort agents.
One of: created_time, last_run_at
body.start_cursorstringOptionalOpaque continuation cursor from the previous page.
body.verbosebooleanOptionalWhether 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 media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
has_morebooleanRequired within parent
next_cursorJSONRequired within parent
next_cursor (anyOf 1)stringAlternative
next_cursor (anyOf 2)nullAlternative
objectstringRequired within parentAlways `list`
Must equal: list
resultsarrayRequired within parentMaximum items: 100
results[]JSONEach item
results[] (anyOf 1)objectAlternativeAdditional keys: allowed
results[] (anyOf 1).agent_typestringRequired within parentWhat 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_versionJSONRequired within parent
results[] (anyOf 1).agent_version (anyOf 1)objectAlternativeAdditional keys: allowed
results[] (anyOf 1).agent_version (anyOf 1).idstringRequired within parentThe ID of the published artifact.
Format: uuid
results[] (anyOf 1).agent_version (anyOf 1).numberJSONRequired within parent
results[] (anyOf 1).agent_version (anyOf 1).number (anyOf 1)numberAlternativeThe version number.
results[] (anyOf 1).agent_version (anyOf 1).number (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results[] (anyOf 1).agent_version (anyOf 1).published_atstringRequired within parentThe ISO 8601 timestamp when this version was published.
results[] (anyOf 1).agent_version (anyOf 2)nullAlternative
results[] (anyOf 1).connectionsarrayRequired within parentIntegrations 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[]JSONEach item
results[] (anyOf 1).connections[] (anyOf 1)ModelAlternativeExpand Get agent — response body — connections item type notion
results[] (anyOf 1).connections[] (anyOf 2)ModelAlternativeExpand Get agent — response body — connections item type slack
results[] (anyOf 1).connections[] (anyOf 3)ModelAlternativeExpand Get agent — response body — connections item type discord
results[] (anyOf 1).connections[] (anyOf 4)ModelAlternativeExpand Get agent — response body — connections item type mcp server
results[] (anyOf 1).connections[] (anyOf 5)ModelAlternativeExpand Get agent — response body — connections item type custom mcp server
results[] (anyOf 1).connections[] (anyOf 6)ModelAlternativeExpand Get agent — response body — connections item account, name, permissions, type
results[] (anyOf 1).created_byJSONRequired within parent
results[] (anyOf 1).created_by (anyOf 1)objectAlternativeAdditional keys: allowed
results[] (anyOf 1).created_by (anyOf 1).idstringRequired within parentThe ID of the user or bot that created this agent.
Format: uuid
results[] (anyOf 1).created_by (anyOf 1).typestringRequired within parentOne of: `user`, `bot`
Known values: user, bot
results[] (anyOf 1).created_by (anyOf 2)nullAlternative
results[] (anyOf 1).created_timestringRequired within parentDate and time when this agent was created.
Format: date-time
results[] (anyOf 1).credit_limitJSONRequired within parentThe 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)JSONAlternative
results[] (anyOf 1).credit_limit (anyOf 1) (anyOf 1)integerAlternativeMinimum: 0
results[] (anyOf 1).credit_limit (anyOf 1) (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results[] (anyOf 1).credit_limit (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
results[] (anyOf 1).credit_limit (anyOf 3)nullAlternative
results[] (anyOf 1).descriptionJSONRequired within parent
results[] (anyOf 1).description (anyOf 1)stringAlternative
results[] (anyOf 1).description (anyOf 2)nullAlternative
results[] (anyOf 1).iconJSONRequired within parent
results[] (anyOf 1).icon (anyOf 1)ModelAlternativeExpand Get agent — response body — icon value
results[] (anyOf 1).icon (anyOf 2)ModelAlternativeExpand Get agent — response body — icon type custom agent avatar
results[] (anyOf 1).icon (anyOf 3)nullAlternative
results[] (anyOf 1).idstringRequired within parentFormat: uuid
results[] (anyOf 1).instructionsJSONOptionalThe agent’s inline instructions when verbose=true, or null when its instructions are stored on a page.
results[] (anyOf 1).instructions (anyOf 1)stringAlternative
results[] (anyOf 1).instructions (anyOf 2)nullAlternative
results[] (anyOf 1).instructions_page_idJSONRequired within parent
results[] (anyOf 1).instructions_page_id (anyOf 1)stringAlternativeFormat: uuid
results[] (anyOf 1).instructions_page_id (anyOf 2)nullAlternative
results[] (anyOf 1).last_edited_timestringRequired within parentDate and time when this agent was last edited.
Format: date-time
results[] (anyOf 1).last_run_atJSONRequired within parentISO 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)stringAlternativeFormat: date-time
Pattern: ^\d{4}-\d{2}-\d{2}T
results[] (anyOf 1).last_run_at (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
results[] (anyOf 1).last_run_at (anyOf 3)nullAlternative
results[] (anyOf 1).modelJSONRequired within parentThe model selection: automatic, or pinned to a public model ID.
results[] (anyOf 1).model (anyOf 1)objectAlternativeAdditional keys: allowed
results[] (anyOf 1).model (anyOf 1).modestringRequired within parentAlways `auto`
Must equal: auto
results[] (anyOf 1).model (anyOf 2)objectAlternativeAdditional keys: allowed
results[] (anyOf 1).model (anyOf 2).idJSONRequired within parentThe 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)stringAlternative
results[] (anyOf 1).model (anyOf 2).id (anyOf 2)nullAlternative
results[] (anyOf 1).model (anyOf 2).modestringRequired within parentAlways `pinned`
Must equal: pinned
results[] (anyOf 1).namestringRequired within parent
results[] (anyOf 1).objectstringRequired within parentAlways `agent`
Must equal: agent
results[] (anyOf 1).pause_reasonJSONRequired within parentWhy 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)stringAlternativeOne 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)nullAlternative
results[] (anyOf 1).statusstringRequired 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).triggersarrayRequired within parentThe 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[]ModelEach itemExpand Get agent — response body — triggers item
results[] (anyOf 2)objectAlternativeAdditional keys: allowed
results[] (anyOf 2).agent_typestringRequired within parentAlways `notion_ai`
Must equal: notion_ai
results[] (anyOf 2).agent_versionnullRequired within parent
results[] (anyOf 2).connectionsarrayRequired within parentMaximum items: 100
results[] (anyOf 2).connections[]JSONEach item
results[] (anyOf 2).connections[] (anyOf 1)ModelAlternativeExpand Get agent — response body — connections item type notion
results[] (anyOf 2).connections[] (anyOf 2)ModelAlternativeExpand Get agent — response body — connections item type slack
results[] (anyOf 2).connections[] (anyOf 3)ModelAlternativeExpand Get agent — response body — connections item type discord
results[] (anyOf 2).connections[] (anyOf 4)ModelAlternativeExpand Get agent — response body — connections item type mcp server
results[] (anyOf 2).connections[] (anyOf 5)ModelAlternativeExpand Get agent — response body — connections item type custom mcp server
results[] (anyOf 2).connections[] (anyOf 6)ModelAlternativeExpand Get agent — response body — connections item account, name, permissions, type
results[] (anyOf 2).created_bynullRequired within parent
results[] (anyOf 2).created_timenullRequired within parent
results[] (anyOf 2).credit_limitnullRequired within parent
results[] (anyOf 2).descriptionnullRequired within parent
results[] (anyOf 2).iconJSONRequired within parent
results[] (anyOf 2).icon (anyOf 1)ModelAlternativeExpand Get agent — response body — icon value
results[] (anyOf 2).icon (anyOf 2)ModelAlternativeExpand Get agent — response body — icon type custom agent avatar
results[] (anyOf 2).idstringRequired within parentAlways `notion_ai`
Must equal: notion_ai
results[] (anyOf 2).instructions_page_idnullRequired within parent
results[] (anyOf 2).last_edited_timenullRequired within parent
results[] (anyOf 2).last_run_atnullRequired within parent
results[] (anyOf 2).modelJSONRequired within parent
results[] (anyOf 2).model (anyOf 1)objectAlternativeAdditional keys: allowed
results[] (anyOf 2).model (anyOf 1).modestringRequired within parentAlways `auto`
Must equal: auto
results[] (anyOf 2).model (anyOf 2)objectAlternativeAdditional keys: allowed
results[] (anyOf 2).model (anyOf 2).idJSONRequired within parentThe 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)stringAlternative
results[] (anyOf 2).model (anyOf 2).id (anyOf 2)nullAlternative
results[] (anyOf 2).model (anyOf 2).modestringRequired within parentAlways `pinned`
Must equal: pinned
results[] (anyOf 2).namestringRequired within parent
results[] (anyOf 2).objectstringRequired within parentAlways `agent`
Must equal: agent
results[] (anyOf 2).pause_reasonnullRequired within parent
results[] (anyOf 2).statusstringRequired within parentAlways `active`
Must equal: active
results[] (anyOf 2).triggersarrayRequired within parentMaximum items: 100
results[] (anyOf 2).triggers[]ModelEach itemExpand Get agent — response body — triggers item
typestringRequired within parentAlways `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

19 more schemas are linked from the tables above, on the schema pages.

Get agent — response body — icon value
FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Get agent — response body — icon value Emoji
$ (anyOf 2)ModelAlternativeExpand Get agent — response body — icon value File
$ (anyOf 3)ModelAlternativeExpand Get agent — response body — icon value External
$ (anyOf 4)ModelAlternativeExpand Get agent — response body — icon value Custom Emoji
$ (anyOf 5)ModelAlternativeExpand 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
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
orarrayRequired within parentMinimum items: 1
or[]JSONEach item
or[] (oneOf 1)objectAlternativeAdditional keys: not allowed
or[] (oneOf 1).idobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 1).id.equalsstringRequired within parent
or[] (oneOf 1).propertystringRequired within parentMust equal: id
or[] (oneOf 2)objectAlternativeAdditional keys: not allowed
or[] (oneOf 2).propertystringRequired within parentMust equal: agent_type
or[] (oneOf 2).stringobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 2).string.equalsstringRequired within parentOne of: notion_ai, custom_agent, autofill_custom_agent
or[] (oneOf 3)objectAlternativeAdditional keys: not allowed
or[] (oneOf 3).peopleobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 3).people.containsstringRequired within parent
or[] (oneOf 3).propertystringRequired within parentMust equal: created_by
or[] (oneOf 4)objectAlternativeAdditional keys: not allowed
or[] (oneOf 4).dateobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 4).date.afterstringOptionalFormat: date-time
or[] (oneOf 4).date.beforestringOptionalFormat: date-time
or[] (oneOf 4).propertystringRequired within parentMust equal: created_time
or[] (oneOf 5)objectAlternativeAdditional keys: not allowed
or[] (oneOf 5).checkboxobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 5).checkbox.equalsbooleanRequired within parent
or[] (oneOf 5).propertystringRequired within parentMust equal: favorited
or[] (oneOf 6)objectAlternativeAdditional keys: not allowed
or[] (oneOf 6).mcp_serverobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 6).mcp_server.containsstringRequired within parent
or[] (oneOf 6).propertystringRequired within parentMust equal: connections
or[] (oneOf 7)objectAlternativeAdditional keys: not allowed
or[] (oneOf 7).propertystringRequired within parentMust equal: status
or[] (oneOf 7).statusobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 7).status.inarrayRequired within parentMinimum items: 1
or[] (oneOf 7).status.in[]stringEach itemOne of: active, disabled, deleted
or[] (oneOf 8)objectAlternativeAdditional keys: not allowed
or[] (oneOf 8).propertystringRequired within parentMust equal: model_mode
or[] (oneOf 8).selectobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 8).select.equalsstringRequired within parentOne of: auto, pinned
or[] (oneOf 9)objectAlternativeAdditional keys: not allowed
or[] (oneOf 9).numberobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 9).number.equalsintegerRequired within parentMinimum: 1
or[] (oneOf 9).propertystringRequired within parentMust equal: agent_version
or[] (oneOf 10)objectAlternativeAdditional keys: not allowed
or[] (oneOf 10).dateobjectRequired within parentAdditional keys: not allowed
or[] (oneOf 10).date.afterstringOptionalFormat: date-time
or[] (oneOf 10).date.beforestringOptionalFormat: date-time
or[] (oneOf 10).propertystringRequired within parentMust equal: last_run_at
Query agents — request body — body filter value or or item value and
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
andarrayRequired within parentMinimum items: 1
and[]JSONEach item
and[] (oneOf 1)objectAlternativeAdditional keys: not allowed
and[] (oneOf 1).idobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 1).id.equalsstringRequired within parent
and[] (oneOf 1).propertystringRequired within parentMust equal: id
and[] (oneOf 2)objectAlternativeAdditional keys: not allowed
and[] (oneOf 2).propertystringRequired within parentMust equal: agent_type
and[] (oneOf 2).stringobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 2).string.equalsstringRequired within parentOne of: notion_ai, custom_agent, autofill_custom_agent
and[] (oneOf 3)objectAlternativeAdditional keys: not allowed
and[] (oneOf 3).peopleobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 3).people.containsstringRequired within parent
and[] (oneOf 3).propertystringRequired within parentMust equal: created_by
and[] (oneOf 4)objectAlternativeAdditional keys: not allowed
and[] (oneOf 4).dateobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 4).date.afterstringOptionalFormat: date-time
and[] (oneOf 4).date.beforestringOptionalFormat: date-time
and[] (oneOf 4).propertystringRequired within parentMust equal: created_time
and[] (oneOf 5)objectAlternativeAdditional keys: not allowed
and[] (oneOf 5).checkboxobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 5).checkbox.equalsbooleanRequired within parent
and[] (oneOf 5).propertystringRequired within parentMust equal: favorited
and[] (oneOf 6)objectAlternativeAdditional keys: not allowed
and[] (oneOf 6).mcp_serverobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 6).mcp_server.containsstringRequired within parent
and[] (oneOf 6).propertystringRequired within parentMust equal: connections
and[] (oneOf 7)objectAlternativeAdditional keys: not allowed
and[] (oneOf 7).propertystringRequired within parentMust equal: status
and[] (oneOf 7).statusobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 7).status.inarrayRequired within parentMinimum items: 1
and[] (oneOf 7).status.in[]stringEach itemOne of: active, disabled, deleted
and[] (oneOf 8)objectAlternativeAdditional keys: not allowed
and[] (oneOf 8).propertystringRequired within parentMust equal: model_mode
and[] (oneOf 8).selectobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 8).select.equalsstringRequired within parentOne of: auto, pinned
and[] (oneOf 9)objectAlternativeAdditional keys: not allowed
and[] (oneOf 9).numberobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 9).number.equalsintegerRequired within parentMinimum: 1
and[] (oneOf 9).propertystringRequired within parentMust equal: agent_version
and[] (oneOf 10)objectAlternativeAdditional keys: not allowed
and[] (oneOf 10).dateobjectRequired within parentAdditional keys: not allowed
and[] (oneOf 10).date.afterstringOptionalFormat: date-time
and[] (oneOf 10).date.beforestringOptionalFormat: date-time
and[] (oneOf 10).propertystringRequired within parentMust equal: last_run_at
Get agent — response body — connections item type notion
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
accountnullRequired within parent
namestringRequired within parent
permissionsarrayRequired within parentMaximum items: 100
permissions[]ModelEach itemExpand Get agent — response body — connections item type notion permissions item
typestringRequired within parentAlways `notion`
Must equal: notion

Referenced models: Get agent — response body — connections item type notion permissions item

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"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.