--- title: "Query agents" method: POST path: "/v1/agents/query" tags: ["Agents"] --- # Query agents `POST /v1/agents/query` ## Headers - `Notion-Version` '2026-03-11', required ## Request body - object - `query` string — Search agent names and descriptions using a case-insensitive substring match. - `filter` union — Filter agents by public properties, optionally combined with and/or. - object - `property` 'id', required - `id` object, required - `equals` string, required - object - `property` 'agent_type', required - `string` object, required - `equals` 'notion_ai' | 'custom_agent' | 'autofill_custom_agent', required - object - `property` 'created_by', required - `people` object, required - `contains` string, required - object - `property` 'created_time', required - `date` object, required - `after` string, date-time - `before` string, date-time - object - `property` 'favorited', required - `checkbox` object, required - `equals` boolean, required - object - `property` 'connections', required - `mcp_server` object, required - `contains` string, required - object - `property` 'status', required - `status` object, required - `in` string[], required - object - `property` 'model_mode', required - `select` object, required - `equals` 'auto' | 'pinned', required - object - `property` 'agent_version', required - `number` object, required - `equals` integer, required - object - `property` 'last_run_at', required - `date` object, required - `after` string, date-time - `before` string, date-time - object - `and` union[], required - union - object - `property` 'id', required - `id` object, required - … - object - `property` 'agent_type', required - `string` object, required - … - object - `property` 'created_by', required - `people` object, required - … - object - `property` 'created_time', required - `date` object, required - … - object - `property` 'favorited', required - `checkbox` object, required - … - object - `property` 'connections', required - `mcp_server` object, required - … - object - `property` 'status', required - `status` object, required - … - object - `property` 'model_mode', required - `select` object, required - … - object - `property` 'agent_version', required - `number` object, required - … - object - `property` 'last_run_at', required - `date` object, required - … - object - `and` union[], required - … - object - `or` union[], required - … - object - `or` union[], required - union - object - `property` 'id', required - `id` object, required - … - object - `property` 'agent_type', required - `string` object, required - … - object - `property` 'created_by', required - `people` object, required - … - object - `property` 'created_time', required - `date` object, required - … - object - `property` 'favorited', required - `checkbox` object, required - … - object - `property` 'connections', required - `mcp_server` object, required - … - object - `property` 'status', required - `status` object, required - … - object - `property` 'model_mode', required - `select` object, required - … - object - `property` 'agent_version', required - `number` object, required - … - object - `property` 'last_run_at', required - `date` object, required - … - object - `and` union[], required - … - object - `or` union[], required - … - `sorts` object[] — Ordered sort precedence. Defaults to created_time descending. - `property` 'created_time' | 'last_run_at', required — Timestamp used to sort agents. - `direction` 'ascending' | 'descending', required — Sort direction. - `start_cursor` string — Opaque continuation cursor from the previous page. - `page_size` integer — Number of agents to return. Maximum: 100. - `verbose` boolean — Whether to include inline instructions for each agent. Defaults to false. - `include_deleted` boolean — Whether to include soft-deleted agents. Defaults to false. ## Response `200` - object - `object` 'list', required — Always `list` - `type` 'agent', required — Always `agent` - `results` union[], required - union - object - `object` 'agent', required — Always `agent` - `id` string, uuid, required - `agent_type` 'custom_agent' | 'autofill_custom_agent', required — What kind of agent this is: "custom_agent" is a standalone agent you chat with; "autofill_custom_agent" fills a database property. - `name` string, required - `description` string, nullable, required - `instructions_page_id` string, uuid, required - `icon` union, required - union - EmojiPageIconResponse - … - FilePageIconResponse - … - ExternalPageIconResponse - … - CustomEmojiPageIconResponse - … - IconPageIconResponse - … - object - `type` 'custom_agent_avatar', required — Type of icon. In this case, a custom agent avatar. - `custom_agent_avatar` object, required — The static and animated URLs for the agent avatar. - … - `model` union, required — The model selection: automatic, or pinned to a public model ID. - object - `mode` 'auto', required — Always `auto` - object - `mode` 'pinned', required — Always `pinned` - `id` string, nullable, required — The public model this agent maps to (e.g. "claude-sonnet-5"), or null for a pre-release / early-access model. - `connections` union[], required — Integrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions. - union - object - … - object - … - object - … - object - … - object - … - object - … - `status` 'active' | 'disabled' | 'deleted', required — "active" when the agent can run; "disabled" when it is paused (see pause_reason); "deleted" when it has been removed. - `pause_reason` 'run_limit' | 'credit_limit' | 'runaway_credit_usage' | 'workspace_credit_limit' | 'failure_limit' | 'mark_session_failed_autopause' | 'disabled_from_workspace_settings' | 'disabled_from_api' | 'disabled_from_agent_settings' | 'disabled_due_to_no_members_with_access' | 'disabled_due_to_lack_of_editors' | 'disabled_by_notion' | 'internal_error' | 'needs_user_review' | 'tool_unavailable', nullable, required — One of: `run_limit`, `credit_limit`, `runaway_credit_usage`, `workspace_credit_limit`, `failure_limit`, `mark_session_failed_autopause`, `disabled_from_workspace_settings`, `disabled_from_api`, `disabled_from_agent_settings`, `disabled_due_to_no_members_with_access`, `disabled_due_to_lack_of_editors`, `disabled_by_notion`, `internal_error`, `needs_user_review`, `tool_unavailable` - `created_by` object, nullable, required - `type` 'user' | 'bot', required — One of: `user`, `bot` - `id` string, uuid, required - `agent_version` object, nullable, required - `id` string, uuid, required - `number` number, required — The version number. - `published_at` string, required — The ISO 8601 timestamp when this version was published. - `created_time` string, date-time, required — Date and time when this agent was created. - `last_edited_time` string, date-time, required — Date and time when this agent was last edited. - `last_run_at` union, required — ISO 8601 timestamp of the agent's most recent run, null if it has never run, or "hidden" when the caller lacks edit access to the agent. - string, date-time - 'hidden' — Always `hidden` - `credit_limit` union, required — The per-agent credit limit that applies to this agent, null when uncapped, or "hidden" when the caller lacks full access to the agent. This is the effective limit computed at runtime, folding in both the agent's own limit and any workspace-admin default. - integer - 'hidden' — Always `hidden` - `triggers` object[], required — The agent's configured triggers, each with a machine type, an enabled flag, and a structured recurrence schedule when applicable. - `type` string, required — Machine trigger type (e.g. "notion.agent.mentioned", "recurrence", "slack.reaction.added"). - `enabled` boolean, required — Whether this trigger is currently enabled. - `schedule` object — Structured recurrence cadence. Present only for recurrence triggers. - `frequency` string, required — Base cadence unit ("hour" | "day" | "week" | "month" | "year"). - `interval` integer, required — Multiplier on the frequency (e.g. every 2 weeks). - `weekdays` string[] — Days of the week the schedule runs (e.g. "monday"). Present for weekly cadences and monthly weekday restrictions. - `monthdays` integer[] — Days of the month the schedule runs. Present for monthly monthday restrictions. - `week_numbers` integer[] — Week-of-month ordinals for a monthly weekday restriction (e.g. [2, 3] for the 2nd and 3rd occurrence); -1 means the last week. - `hour` integer — Hour of day (0–23) the schedule runs. - `minute` integer — Minute of the hour (0–59) the schedule runs. - `timezone` string — IANA timezone (e.g. "America/New_York"). - `start_date` string — ISO 8601 timestamp the schedule starts from. - `end` union — When the schedule stops, when it is bounded. - … - `config` object — Remaining per-type trigger configuration (e.g. watched channel ids, reaction config), keys in snake_case. Present only when the trigger carries such state. - `instructions` string, nullable — The agent's inline instructions when verbose=true, or null when its instructions are stored on a page. - object - `object` 'agent', required — Always `agent` - `id` 'notion_ai', required — Always `notion_ai` - `agent_type` 'notion_ai', required — Always `notion_ai` - `name` 'Notion Agent', required — Always `Notion Agent` - `description` unknown, required - `instructions_page_id` unknown, required - `icon` union, required - union - EmojiPageIconResponse - … - FilePageIconResponse - … - ExternalPageIconResponse - … - CustomEmojiPageIconResponse - … - IconPageIconResponse - … - object - `type` 'custom_agent_avatar', required — Type of icon. In this case, a custom agent avatar. - `custom_agent_avatar` object, required — The static and animated URLs for the agent avatar. - … - `model` union, required - object - `mode` 'auto', required — Always `auto` - object - `mode` 'pinned', required — Always `pinned` - `id` string, nullable, required — The public model this agent maps to (e.g. "claude-sonnet-5"), or null for a pre-release / early-access model. - `connections` union[], required - union - object - … - object - … - object - … - object - … - object - … - object - … - `status` 'active', required — Always `active` - `pause_reason` unknown, required - `created_by` unknown, required - `agent_version` unknown, required - `created_time` unknown, required - `last_edited_time` unknown, required - `last_run_at` unknown, required - `credit_limit` unknown, required - `triggers` object[], required - `type` string, required — Machine trigger type (e.g. "notion.agent.mentioned", "recurrence", "slack.reaction.added"). - `enabled` boolean, required — Whether this trigger is currently enabled. - `schedule` object — Structured recurrence cadence. Present only for recurrence triggers. - `frequency` string, required — Base cadence unit ("hour" | "day" | "week" | "month" | "year"). - `interval` integer, required — Multiplier on the frequency (e.g. every 2 weeks). - `weekdays` string[] — Days of the week the schedule runs (e.g. "monday"). Present for weekly cadences and monthly weekday restrictions. - `monthdays` integer[] — Days of the month the schedule runs. Present for monthly monthday restrictions. - `week_numbers` integer[] — Week-of-month ordinals for a monthly weekday restriction (e.g. [2, 3] for the 2nd and 3rd occurrence); -1 means the last week. - `hour` integer — Hour of day (0–23) the schedule runs. - `minute` integer — Minute of the hour (0–59) the schedule runs. - `timezone` string — IANA timezone (e.g. "America/New_York"). - `start_date` string — ISO 8601 timestamp the schedule starts from. - `end` union — When the schedule stops, when it is bounded. - … - `config` object — Remaining per-type trigger configuration (e.g. watched channel ids, reaction config), keys in snake_case. Present only when the trigger carries such state. - `has_more` boolean, required - `next_cursor` string, nullable, required ## Other responses - `400` - `401` - `403` - `404` - `406` - `409` - `429` - `500` - `503` - `504` - `529` --- [API](https://skmtc.net/notion/apis/notion-api.md) · [All operations](https://skmtc.net/notion/apis/notion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notion/notion-api/revisions/dee5763763b0/schema)