# List conversations

> List agent conversations

- Source: https://www.taskade.com/docs/actions/list-conversations
- Section: Action API
- Endpoint: `POST /listConversations` (API v2)
- Index of all pages: https://www.taskade.com/docs/llms.txt

## POST `/listConversations`

List agent conversations

Base URL: `https://www.taskade.com/api/v2`

### Authentication

Send a personal access token or an OAuth 2.0 access token as a bearer token. Create a personal access token at [taskade.com/settings/api](https://www.taskade.com/settings/api).

```http
Authorization: Bearer tskdp_your_token_here
```

### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agentId` | `string` | Yes | — |
| `limit` | `number` | No | — |
| `page` | `number` | No | — |

### Example request

```bash
curl -X POST "https://www.taskade.com/api/v2/listConversations" \
  -H "Authorization: Bearer $TASKADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"<agentId>"}'
```

### Responses

#### `200` — Default response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` | Yes | — |
| `items` | `Convo[]` | Yes | — |
| `items[].id` | `string` | Yes | — |
| `items[].space_agent_id` | `string` | Yes | — |
| `items[].status` | `string` | Yes | Allowed values: `in_progress`, `idle`, `requires_review`. |
| `items[].title` | `string` | No | — |
| `items[].data` | `object` | Yes | — |
| `items[].data.llm` | `object` | No | — |
| `items[].data.llm.type` | `string` | Yes | Allowed values: `openai`, `anthropic`, `google`, `alibaba`, `minimax`, `zai`, `moonshotai`, `deepseek`, `xai`, `xiaomi`, `nvidia`, `typesafe-ai`. |
| `items[].data.llm.name` | `string` | Yes | Allowed values: `gpt-3.5-turbo`, `gpt-4o`, `gpt-4-turbo`, `gpt-4o-mini`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `o3-mini:low`, `o3-mini:medium`, `o3-mini:high`, `o4-mini:low`, `o4-mini:medium`, `o4-mini:high`, `openai/gpt-4o`, `openai/gpt-4o-mini`, `openai/gpt-4.1`, `openai/gpt-4.1-mini`, `openai/gpt-4.1-nano`, `openai/gpt-5`, `openai/gpt-5:high`, `openai/gpt-5-mini`, `openai/gpt-5-mini:high`, `openai/gpt-5-nano`, `openai/gpt-5-nano:high`, `openai/gpt-5.1`, `openai/gpt-5.1:low`, `openai/gpt-5.1:medium`, `openai/gpt-5.1:high`, `openai/gpt-5.1-codex`, `openai/gpt-5.1-codex:low`, `openai/gpt-5.1-codex:medium`, `openai/gpt-5.1-codex:high`, `openai/gpt-5.1-codex-max`, `openai/gpt-5.1-codex-max:medium`, `openai/gpt-5.1-codex-max:high`, `openai/gpt-5.1-codex-max:xhigh`, `openai/gpt-5.2`, `openai/gpt-5.2:medium`, `openai/gpt-5.2:high`, `openai/gpt-5.2:xhigh`, `openai/gpt-5.2-codex`, `openai/gpt-5.2-codex:medium`, `openai/gpt-5.2-codex:high`, `openai/gpt-5.2-codex:xhigh`, `openai/gpt-5.3-codex`, `openai/gpt-5.3-codex:medium`, `openai/gpt-5.3-codex:high`, `openai/gpt-5.3-codex:xhigh`, `openai/gpt-5.3-chat`, `openai/gpt-5.4`, `openai/gpt-5.4:medium`, `openai/gpt-5.4:high`, `openai/gpt-5.4:xhigh`, `openai/gpt-5.4-pro`, `openai/gpt-5.4-pro:medium`, `openai/gpt-5.4-pro:high`, `openai/gpt-5.4-pro:xhigh`, `openai/gpt-5.4-mini`, `openai/gpt-5.4-nano`, `openai/gpt-5.5`, `openai/gpt-5.5:medium`, `openai/gpt-5.5:high`, `openai/gpt-5.5:xhigh`, `openai/gpt-5.5-pro`, `openai/gpt-5.5-pro:medium`, `openai/gpt-5.5-pro:high`, `openai/gpt-5.5-pro:xhigh`, `openai/gpt-5.6-luna`, `openai/gpt-5.6-luna:high`, `openai/gpt-5.6-sol`, `openai/gpt-5.6-sol:high`, `openai/gpt-5.6-terra`, `openai/gpt-5.6-terra:high`, `openai/gpt-6-luna`, `openai/gpt-6-luna:low`, `openai/gpt-6-luna:high`, `openai/gpt-6-luna:xhigh`, `openai/gpt-6-sol`, `openai/gpt-6-sol:high`, `openai/gpt-6.1-sol`, `openai/gpt-6.1-sol:high`, `openai/gpt-6.1-sol:xhigh`, `openai/gpt-6.1-terra`, `anthropic/claude-4.0-sonnet`, `anthropic/claude-4.0-opus`, `anthropic/claude-sonnet-4.5`, `anthropic/claude-sonnet-4.5:thinking`, `anthropic/claude-haiku-4.5`, `anthropic/claude-haiku-4.5:thinking`, `anthropic/claude-opus-4.5`, `anthropic/claude-opus-4.5:thinking`, `anthropic/claude-opus-4.8`, `anthropic/claude-opus-4.8:thinking`, `anthropic/claude-fable-5`, `anthropic/claude-fable-5:thinking`, `anthropic/claude-opus-4.7`, `anthropic/claude-opus-4.7:thinking`, `anthropic/claude-opus-4.6`, `anthropic/claude-opus-4.6:thinking`, `anthropic/claude-opus-5`, `anthropic/claude-opus-5:thinking`, `anthropic/claude-opus-5.5`, `anthropic/claude-opus-5.5:thinking`, `anthropic/claude-sonnet-5`, `anthropic/claude-sonnet-5:thinking`, `anthropic/claude-sonnet-5.5`, `anthropic/claude-sonnet-5.5:thinking`, `anthropic/claude-sonnet-4.6`, `anthropic/claude-sonnet-4.6:thinking`, `anthropic/claude-3.5-sonnet`, `anthropic/claude-3.5-haiku`, `anthropic/claude-3.7-sonnet`, `google/gemini-2.5-pro`, `google/gemini-2.5-flash`, `google/gemini-2.5-flash-lite`, `google/gemini-3-pro-preview`, `google/gemini-3-flash-preview`, `google/gemini-3-flash`, `google/gemini-3.1-pro-preview`, `google/gemini-3.1-flash-lite-preview`, `google/gemini-3.1-flash-lite`, `google/gemini-3.5-flash`, `google/gemini-3.6-flash`, `google/gemini-3.7-flash`, `google/gemma-4-31b-it`, `google/gemma-4-26b-a4b-it`, `alibaba/qwen3.7-plus`, `alibaba/qwen3.6-plus`, `alibaba/qwen3.6-27b`, `alibaba/qwen-3.6-max-preview`, `alibaba/qwen3.7-max`, `minimax/minimax-m3`, `minimax/minimax-m2.7`, `zai/glm-5.1`, `zai/glm-5.2`, `zai/glm-5.3`, `moonshotai/kimi-k2.6`, `moonshotai/kimi-k2.7-code`, `moonshotai/kimi-k3`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `deepseek/deepseek-v4.1-flash`, `deepseek/deepseek-v4.1-flash-1017`, `deepseek/deepseek-v4-pro-0813`, `deepseek/deepseek-v4-pro:high`, `deepseek/deepseek-v4-pro:max`, `deepseek/deepseek-v4-flash:max`, `xai/grok-4.3`, `xai/grok-4.5`, `xai/grok-4.6`, `xai/grok-build-0.1`, `xai/grok-4.7`, `xiaomi/mimo-v2.5`, `xiaomi/mimo-v2.5-pro`, `nvidia/nemotron-3-ultra-550b-a55b`, `nvidia/nemotron-3-super-120b-a12b`, `typesafe-ai/jev`. |
| `items[].data.endedAt` | `number` | No | — |

A nested field marked Yes is required whenever its parent object is present.

### Errors

Errors return an `ok: false` envelope. Rate limiting returns `429` with `x-rate-limit-limit`, `x-rate-limit-remaining` and `x-rate-limit-reset` headers. `x-rate-limit-reset` is the number of seconds until the window reopens. `Retry-After` is not sent, so schedule retries from `x-rate-limit-reset`; retrying sooner will fail again.

```json
{ "ok": false, "message": "Unauthorized", "code": "UNAUTHORIZED" }
```

Rate limits for this version: enforced per endpoint; ceilings are not published and can change without notice. A `429` response carries `x-rate-limit-limit`, `x-rate-limit-remaining`, and `x-rate-limit-reset` (seconds until the window reopens). Back off from those headers rather than hardcoding numbers. If you need sustained throughput, prefer batching (operations like `/createTask` accept arrays) over tightening polling loops. See [Rate limits](https://www.taskade.com/docs/getting-started/action-api-guide#rate-limits).