# List Real-time STT agents (/en/api-reference/api-ref/speech-to-text/list)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Retrieves Real-time STT agents that match specified criteria.

- OpenAPI: /openapi/speech-to-text/v7.en.yaml
- Operation ID: list
- Method: GET
- Path: /api/speech-to-text/v1/projects/{appid}/agents
- Endpoint: https://api.agora.io/api/speech-to-text/v1/projects/{appid}/agents

## Servers

- https://api.agora.io

Use this method to retrieve a list of real-time transcription and translation agents that match specified criteria.


## Authorization

This endpoint requires authentication.

- `BasicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of the project.
- `channel` (query, optional, string) - Filters the agent list by channel name.
- `from_time` (query, optional, integer) - The start of the query time range, as a Unix timestamp in seconds. Defaults to `1 day ago`.
- `to_time` (query, optional, integer) - The end of the query time range, as a Unix timestamp in seconds. Defaults to the current time.
- `state` (query, optional, string) - Filters agents by status. Only one status value can be specified per request:
- `0` - `IDLE`: The agent is not initialized.
- `1` - `STARTING`: The agent is starting.
- `2` - `RUNNING`: The agent is running.
- `3` - `STOPPING`: The agent is exiting.
- `4` - `STOPPED`: The agent exited successfully.
- `5` - `RECOVERING`: The agent is recovering.
- `6` - `FAILED`: The agent exited with a failure.
  - Default: `2`
- `limit` (query, optional, integer) - The maximum number of agents to return per page.
  - Default: `20`
- `cursor` (query, optional, string) - The pagination cursor. Set this to the `agent_id` of the last item from the previous page to retrieve the next page of results.

## Request body

No request body.

## Request examples

### curl

```bash
curl --request GET \
  --url 'https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents?state=2&limit=20' \
  --header 'Authorization: Basic <credentials>'
```

### Python

```python
import requests

url = "https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents"

params = {
    "state": 2,
    "limit": 20
}
headers = {"Authorization": "Basic <credentials>"}

response = requests.request("GET", url, headers=headers, params=params)

print(response.text)
```

### Node.js

```javascript
const url = 'https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents?state=2&limit=20';
const options = {
  method: 'GET',
  headers: {Authorization: 'Basic <credentials>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```


### Response

- If the returned status code is `200`, the request was successful. The response body contains the result of the request.


## Responses

### 200

OK

- `data` (object)
  - `data.count` (integer) - The number of agents returned in this response.
  - `data.list` (array) - The list of agents matching the query criteria.
    - `data.list.items` (object)
      - `data.list.items.start_ts` (integer) - The Unix timestamp (in seconds) when the agent was created.
      - `data.list.items.status` (string) - The current status of the agent:
- `IDLE`: The agent is not initialized.
- `STARTING`: The agent is starting.
- `RUNNING`: The agent is running.
- `STOPPING`: The agent is exiting.
- `STOPPED`: The agent exited successfully.
- `RECOVERING`: The agent is recovering.
- `FAILED`: The agent exited with a failure.
      - `data.list.items.agent_id` (string) - The agent ID.
- `meta` (object) - Metadata about the returned list.
  - `meta.cursor` (string) - The pagination cursor for the next page of results.
  - `meta.total` (integer) - The total number of agents matching the query criteria.
- `status` (string) - The request status.
### default

Error response.

- `detail` (string) - Details of the request failure.
- `reason` (string) - The reason why the request failed.

### Response

Refer to the detail and reason fields to understand the possible reasons for failure.


## Response examples

### 200

```json
{
  "data": {
    "count": 1,
    "list": [
      {
        "start_ts": 1735035893,
        "status": "RUNNING",
        "agent_id": "1NT29X11GQSxxxxx80BEIN56XF"
      }
    ]
  },
  "meta": {
    "cursor": "",
    "total": 1
  },
  "status": "ok"
}
```
### default

```json
{
  "detail": "Details of the request failure.",
  "reason": "The reason why the request failed."
}
```