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

# List all agents

`GET /v1/agents`

## Request

- Base URL: `https://api.notifly.io`
- URL: `https://api.notifly.io/v1/agents`
- Auth: API key in header `Authorization`

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

## Response `200`

OK

- object
  - `data` 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.dev/notifly/apis/notifly-api.md) · [All operations](https://skmtc.dev/notifly/apis/notifly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/notifly/apis/notifly-api/revisions/af909b9e1e57?raw)