> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unleashx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Voice Agents

# Get Voice Agent API

This documentation explains how to retrieve details of voice agents using the API.

## Endpoint

**GET** `/api/v1/global/agents/get`

or

**POST** `/api/v1/global/agents/get`

## Authentication

Include your API token in the request header:

```
token: <your_api_token>
```

or

```
api_access_token: <your_api_token>
```

## Request Body (for POST)

### Get Specific Agent

```json theme={null}
{
  "agent_id": 123
}
```

### Get All Agents

```json theme={null}
{}
```

### Get Agents by Type

```json theme={null}
{
  "agent_type": 3
}
```

### Get Specific Agent with Type Filter

```json theme={null}
{
  "agent_id": 123,
  "agent_type": 3
}
```

## Query Parameters (for GET)

### Get Specific Agent

```
?agent_id=123
```

### Get All Agents

```
(no parameters)
```

### Get Agents by Type

```
?agent_type=3
```

### Get Specific Agent with Type Filter

```
?agent_id=123&agent_type=3
```

## Optional Fields

| Field        | Type    | Description                                                      |
| ------------ | ------- | ---------------------------------------------------------------- |
| `agent_id`   | integer | ID of the agent to retrieve. If not provided, returns all agents |
| `agent_type` | integer | Filter by agent type. See Agent Types below                      |

## Agent Types

| ID | Type      | Description                               |
| -- | --------- | ----------------------------------------- |
| 2  | Chat      | Chat-based agents                         |
| 3  | Telephony | Voice/telephony agents (for making calls) |
| 4  | General   | General purpose agents                    |

**Note:** For voice/telephony agents that can make calls, use `agent_type: 3`.

## Calling Types

**Important:** The `calling_type` field in the response indicates whether the agent is configured for outbound or inbound calls.

| ID   | Type         | Description                                                                                   |
| ---- | ------------ | --------------------------------------------------------------------------------------------- |
| 1    | **Outbound** | Agent makes calls to customers. The agent initiates calls to phone numbers.                   |
| 2    | **Inbound**  | Agent receives calls from customers. Customers call your phone numbers and the agent answers. |
| null | **Not Set**  | Calling type is not configured for this agent.                                                |

**Note:**

* `calling_type: 1` means the agent is configured for outbound calling (making calls)
* `calling_type: 2` means the agent is configured for inbound calling (receiving calls)
* `calling_type: null` means the calling type is not configured

## Success Response

### Single Agent Response (when agent\_id is provided)

**Status Code:** `200 OK`

```json theme={null}
{
  "error": false,
  "code": 200,
  "message": "Voice agent retrieved successfully",
  "timestamp": 1767638299411,
  "data": {
    "success": true,
    "message": "Voice agent retrieved successfully",
    "data": {
      "agent_id": 1048,
      "agent_name": "Test Agent",
      "description": "Test description",
      "status": 3,
      "agent_type": 3,
      "voice_id": "KYiVPerWcenyBTIvWbfY",
      "voice_provider": 1,
      "transcriber_provider": null,
      "calling_type": null,
      "created_on": "2026-01-01T07:44:46.000Z",
      "updated_on": "2026-01-01T07:44:46.000Z"
    }
  }
}
```

### Multiple Agents Response (when agent\_id is not provided)

**Status Code:** `200 OK`

```json theme={null}
{
  "error": false,
  "code": 200,
  "message": "Voice agents retrieved successfully",
  "timestamp": 1767638262719,
  "data": {
    "success": true,
    "total": 35,
    "data": [
      {
        "agent_id": 1049,
        "agent_name": "Flow Test",
        "description": "",
        "status": 3,
        "agent_type": 3,
        "voice_id": "KYiVPerWcenyBTIvWbfY",
        "voice_provider": 1,
        "transcriber_provider": null,
        "calling_type": null,
        "created_on": "2026-01-02T14:13:19.000Z",
        "updated_on": "2026-01-02T14:13:19.000Z"
      },
      {
        "agent_id": 1048,
        "agent_name": "Test Agent",
        "description": "",
        "status": 3,
        "agent_type": 3,
        "voice_id": "KYiVPerWcenyBTIvWbfY",
        "voice_provider": 1,
        "transcriber_provider": null,
        "calling_type": null,
        "created_on": "2026-01-01T07:44:46.000Z",
        "updated_on": "2026-01-01T07:44:46.000Z"
      }
    ]
  }
}
```

## Response Fields

| Field                  | Type            | Description                                                           |
| ---------------------- | --------------- | --------------------------------------------------------------------- |
| `agent_id`             | integer         | Unique identifier for the agent                                       |
| `agent_name`           | string          | Name of the agent                                                     |
| `description`          | string          | Description of the agent (can be empty string)                        |
| `status`               | integer         | Agent status: 1 = Active, 3 = Inactive, 2 = Deleted                   |
| `agent_type`           | integer         | Type of agent: 2 = Chat, 3 = Telephony, 4 = General                   |
| `voice_id`             | string          | Voice ID being used (can be a string identifier)                      |
| `voice_provider`       | integer         | Voice provider ID (see Create Agent docs for options)                 |
| `transcriber_provider` | integer \| null | Speech-to-text provider ID (can be null)                              |
| `calling_type`         | integer \| null | Calling type (see Calling Types below). Can be null if not configured |
| `created_on`           | string          | Creation timestamp (ISO 8601 format)                                  |
| `updated_on`           | string          | Last update timestamp (ISO 8601 format)                               |

**Note:**

* `transcriber_provider` and `calling_type` can be `null` if not configured
* `voice_id` is typically a string identifier, not an integer
* Timestamps are in ISO 8601 format (e.g., "2026-01-01T07:44:46.000Z")

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": true,
  "message": "Agent ID is required"
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": true,
  "message": "Invalid Auth Key or Session Expired"
}
```

### 404 Not Found

```json theme={null}
{
  "error": true,
  "message": "Agent not found"
}
```

## Example Requests

### Get Specific Agent (GET)

```bash theme={null}
curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/get?agent_id=123" \
  -H "token: your_api_token_here"
```

### Get Specific Agent (POST)

```bash theme={null}
curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{
    "agent_id": 123
  }'
```

### Get All Agents (GET)

```bash theme={null}
curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/get" \
  -H "token: your_api_token_here"
```

### Get All Agents (POST)

```bash theme={null}
curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{}'
```

### Get All Telephony Agents (GET)

```bash theme={null}
curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/get?agent_type=3" \
  -H "token: your_api_token_here"
```

### Get All Telephony Agents (POST)

```bash theme={null}
curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{
    "agent_type": 3
  }'
```

### Get All Chat Agents (POST)

```bash theme={null}
curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{
    "agent_type": 2
  }'
```

### Get All General Agents (POST)

```bash theme={null}
curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{
    "agent_type": 4
  }'
```

## Notes

* If `agent_id` is provided, returns details of that specific agent.
* If `agent_id` is not provided, returns a list of all agents.
* If `agent_type` is provided, filters agents by type (2 = Chat, 3 = Telephony, 4 = General).
* The `agent_type` filter only applies when getting all agents (not when getting a specific agent by ID).
* The agents must belong to your workspace.
* Deleted agents (status = 2) will not be returned.
* Use the `status` field to check if the agent is active before making calls.
* For making calls, use agents with `agent_type: 3` (Telephony).
* Response includes a wrapper with `error`, `code`, `message`, `timestamp`, and `data` fields.
* The actual agent data is nested in `data.data` for single agent, or `data.data` array for multiple agents.


## OpenAPI

````yaml api-reference/openapi.json GET /agents/get
openapi: 3.1.0
info:
  title: >-
    UnleashX - Build human like conversations | Voice Agents | Automations | AI
    Workforce
  version: 1.0.0
  description: UnleashX - Your home for human like conversations
servers:
  - url: https://www.tryunleashx.com/api/v1/global/
security:
  - bearerAuth: []
paths:
  /agents/get:
    get:
      tags:
        - Voice AI
      summary: Get voice agents
      parameters:
        - name: token
          in: header
          required: true
          description: API token for authentication
          schema:
            type: string
        - name: agent_id
          in: query
          required: false
          description: ID of the agent to retrieve. If not provided, returns all agents
          schema:
            type: integer
        - name: agent_type
          in: query
          required: false
          description: 'Filter by agent type: 2 = Chat, 3 = Telephony, 4 = General'
          schema:
            type: integer
      responses:
        '200':
          description: Voice agents retrieved successfully
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '404':
          description: Agent not found
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````