# 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

## Servers

- https://api.agora.io

## Parameters

- `appid` (path, required) - The App ID of the project.
- `channel` (query, optional) - Filters the agent list by channel name.
- `from_time` (query, optional) - The start of the query time range, as a Unix timestamp in seconds. Defaults to `1 day ago`.
- `to_time` (query, optional) - The end of the query time range, as a Unix timestamp in seconds. Defaults to the current time.
- `state` (query, optional) - 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.
- `limit` (query, optional) - The maximum number of agents to return per page.
- `cursor` (query, optional) - 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.

## Responses

### 200

OK

- `data` (object)
  - `data.count` (integer) - The number of agents returned in this response.
No schema.
  - `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.
No schema.
      - `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.
No schema.
      - `data.list.items.agent_id` (string) - The agent ID.
No schema.
- `meta` (object) - Metadata about the returned list.
  - `meta.cursor` (string) - The pagination cursor for the next page of results.
No schema.
  - `meta.total` (integer) - The total number of agents matching the query criteria.
No schema.
- `status` (string) - The request status.
No schema.
### default

Error response.

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