---
title: "GET /agents"
method: GET
path: "/agents"
---

# GET /agents

`GET /agents`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/agents`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Query parameters

- `cursor` string: Opaque cursor from a previous response to fetch the next page
- `limit` integer: Maximum number of items to return per page (1–100, default 20)
- `orgId` string: Filter agents by organization ID
- `status` 'ACTIVE' | 'SUSPENDED' | 'DELETED': Filter agents by lifecycle status
- `query` string: Free-text search query to filter agents by name or slug

## Response `200`

OK

- object: Paginated list of agents
  - `items` object[], required: Array of agent resources matching the query
    - `id` string, required: Unique identifier of the agent
    - `orgId` string, required: Organization ID that owns this agent
    - `name` string, required: Human-readable display name
    - `slug` string, required: URL-friendly unique identifier
    - `status` 'ACTIVE' | 'SUSPENDED' | 'DELETED', required: Current lifecycle status
    - `apiKeyPrefix` string, nullable, required: Prefix of the agent's API key for identification, or null if no key is set
    - `keyRotatedAt` string, date-time, nullable, required: ISO 8601 timestamp of the last API-key rotation, null if never rotated
    - `metadata` object, required: Arbitrary key-value metadata
    - `voiceId` string, nullable, required: The agent's chosen voice id, or null for the system default.
    - `emailIdentities` object[], required: Email identities associated with this agent
      - `id` string, required: Unique identifier of the email identity
      - `email` string, email, required: Full email address
      - `domain` string, required: Domain portion of the email address
      - `localPart` string, required: Local part (before the @) of the email address
      - `isPrimary` boolean, required: Whether this is the agent's primary email identity
      - `verified` boolean, required: Whether the email address has been verified
      - `createdAt` string, date-time, required: Timestamp when the email identity was created
    - `phoneIdentities` object[], required: Phone identities associated with this agent
      - `id` string, required: Unique identifier of the phone identity
      - `phoneNumber` string, required: Phone number in E.164 format
      - `providerId` string, nullable, required: Opaque carrier-side identifier for this phone number
      - `capabilities` object, required: Communication capabilities supported by this phone number
        - `sms` boolean: Whether the number supports SMS messaging
        - `mms` boolean: Whether the number supports MMS messaging
        - `voice` boolean: Whether the number supports voice calls
      - `tenDlcStatus` 'PENDING' | 'REGISTERED' | 'REJECTED' | 'NOT_REQUIRED' | 'UNREGISTERED', required: 10DLC campaign registration status
      - `isPrimary` boolean, required: Whether this is the agent's primary phone identity
      - `voiceId` string, nullable, required: The voice this number answers with, from the voice catalog. Null means it uses the agent's voice, and then the system default. Set it per number so one agent's support line and sales line can sound different.
      - `createdAt` string, date-time, required: Timestamp when the phone identity was created
    - `readiness` object: Per-capability readiness summary. Optional for backward compatibility — clients without readiness handling continue to work; clients that branch on it get the delayed-verification gap closed.
      - `canSendEmail` boolean, required: True iff the agent has at least one verified email identity right now
      - `canReceiveEmail` boolean, required: True iff inbound MX is configured for the agent's primary domain
      - `canSendSms` boolean, required: True iff the agent has a provisioned phone identity with SMS capability that's past 10DLC if required
      - `canPlaceVoiceCall` boolean, required: True iff the agent has a phone identity with voice capability
      - `blockers` object[], required: All current blockers across capabilities; empty array means fully ready
        - `code` 'IDENTITY_NOT_VERIFIED' | 'DOMAIN_NOT_VERIFIED' | 'PHONE_NOT_PROVISIONED', required: Stable code matching the typed error thrown at call time
        - `field` string, required: JSON-path-ish location of the failing field, e.g. emailIdentities[0]
        - `hint` string, required: Human-readable remediation hint
        - `remediationUrl` string: Optional pointer to where the user can resolve this blocker
    - `createdAt` string, date-time, required: Timestamp when the agent was created
    - `updatedAt` string, date-time, required: Timestamp when the agent was last updated
  - `pagination` object, required: Pagination metadata for retrieving additional pages
    - `nextCursor` string, nullable, required: Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results
    - `hasMore` boolean, required: Whether additional pages of results are available

---

[API](https://skmtc.dev/useanima/apis/anima-api.md) · [All operations](https://skmtc.dev/useanima/apis/anima-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useanima/apis/anima-api/revisions/aaa148188980?raw)