---
title: "List all agents"
method: GET
path: "/v1/agents"
tags: ["Agents"]
---

# List all agents

`GET /v1/agents`

Retrieve a cursor-paginated list of agents for the current environment. Use **after**, **before**, **limit**, **orderBy**, and **orderDirection** query parameters.

## Query parameters

- `after` string
- `before` string
- `limit` number
- `orderDirection` 'ASC' | 'DESC'
- `orderBy` string
- `includeCursor` boolean
- `identifier` string

## Headers

- `idempotency-key` string

## Response `200`

OK

- ListAgentsResponseDto
  - `data` AgentResponseDto[], required — List of returned agents
    - `_id` string, required
    - `name` string, required
    - `identifier` string, required
    - `description` string
    - `behavior` AgentBehaviorDto, required
      - `acknowledgeOnReceived` boolean — Acknowledge incoming messages. On platforms that support a native typing indicator (e.g. Slack, WhatsApp, Microsoft Teams, Telegram), shows a "Typing…" indicator while the agent processes the message. On platforms that do not (e.g. Email), reacts with an "eyes" emoji to the first inbound message in a thread. Default: true
      - `reactionOnResolved` object, nullable — Cross-platform emoji name for resolved conversations (e.g. "check", "star"). Set to null to disable. Default: "check"
      - `subscriberAccess` 'open' | 'restricted' — Controls whether the agent accepts inbound messages from senders not yet linked to a subscriber, across all channels. "open" on managed agents auto-creates a lightweight subscriber so the agent can reply; on custom-code / self-hosted agents, the turn is forwarded to the bridge with a null subscriber. "restricted" rejects unknown senders with a managed denial reply (any runtime). Optional on update (partial PATCH). Persisted agents always have a value — managed create defaults to "open"; self-hosted create defaults to "restricted".
    - `active` boolean, required
    - `bridgeUrl` string — Production bridge URL
    - `devBridgeUrl` string — Development bridge URL (set by npx novu dev)
    - `devBridgeActive` boolean — Whether the dev bridge override is active
    - `runtime` 'self-hosted' | 'managed' — Whether the agent brain is self-hosted (bridge) or managed by a third-party provider
    - `visibility` 'public' | 'private' — Discovery scope of the agent. Always `public` today; reserved for the upcoming private-agents feature.
    - `managedRuntime` ManagedRuntimeResponseDto
      - `providerId` string, required
      - `integrationId` string, required
      - `externalAgentId` string, required
      - `externalEnvironmentId` string — The provider-side environment that hosts this agent. Hydrated from the linked integration credentials. Absent when the integration has not been provisioned.
      - `externalWorkspaceId` string — The provider-side workspace id used in console deep links. Defaults to `'default'` (the auto-created Default Workspace). Hydrated from the linked integration credentials.
      - `consoleUrl` string — Deep link to the agent in the provider console (e.g. platform.claude.com).
      - `tools` AgentToolDto[] — Live tools enabled on the managed-runtime provider for this agent. Sourced from the provider on read; omitted when the provider is temporarily unreachable.
        - `externalId` string, required
        - `name` string, required
        - `type` 'builtin' | 'custom', required
        - `description` string
      - `mcpServers` AgentMcpServerDto[] — MCP servers enabled on this agent, projected onto the runtime catalog `{ externalId, name, url }` shape. Mongo is the source of truth; the projection matches what the provider sees. Omitted when the provider read fails after a managed-agent write.
        - `externalId` string, required
        - `name` string, required
        - `url` string, required
      - `systemPrompt` string — System prompt used when invoking the agent.
    - `_environmentId` string, required
    - `_organizationId` string, required
    - `createdBy` string — Mongo user id of the user who created the agent
    - `createdAt` string, required
    - `updatedAt` string, required
    - `integrations` AgentIntegrationSummaryDto[]
      - `integrationId` string, required — Integration document id.
      - `providerId` string, required
      - `name` string, required
      - `identifier` string, required
      - `channel` 'in_app' | 'email' | 'sms' | 'chat' | 'push' | 'tool' — Channel type through which the message is sent
      - `active` boolean, required
    - `exceedsPlanLimit` boolean — Cloud only. `true` when the agent falls outside the organization plan agent limit (by creation order among active agents — inactive agents do not consume slots). Only plan limits produce this flag — system-capped organizations (enterprise/unlimited tiers) are never over-limit. Over-limit agents are still stored but will not respond to inbound messages until the plan is upgraded or older agents are deactivated.
  - `next` string, nullable, required — The cursor for the next page of results, or null if there are no more pages.
  - `previous` string, nullable, required — The cursor for the previous page of results, or null if this is the first page.
  - `totalCount` number, required — The total count of items (up to 50,000)
  - `totalCountCapped` boolean, required — Whether there are more than 50,000 results available
  - `planUsage` AgentPlanUsageDto
    - `used` number, required — Current usage count for the resource in this environment.
    - `limit` number, required — Amount included in the organization plan.
    - `totalCreated` number, required — Total agents in this environment, including inactive ones.
    - `creationLimit` number, required — Hard cap on total agents the organization can create per environment. For plan-limited tiers this is the plan limit plus a small grace buffer; for unlimited tiers it is the platform system limit.
    - `limitSource` 'plan' | 'system', required — Which constraint produced the limits. `plan` limits are lifted by upgrading; `system` limits (platform cap or per-organization override) require contacting the Novu team.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `405` — Method Not Allowed
- `409` — Conflict
- `413` — Payload Too Large
- `414` — URI Too Long
- `415` — Unsupported Media Type
- `422` — Unprocessable Entity
- `429` — The client has sent too many requests in a given amount of time.
- `500` — Internal Server Error
- `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

---

[API](https://skmtc.net/novu/apis/novu-api.md) · [All operations](https://skmtc.net/novu/apis/novu-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/novu/novu-api/revisions/c2b2fa0d5d48/schema)