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

# List Tasks

> List all tasks for the authenticated API key with pagination

# List Tasks

Retrieve a paginated list of all tasks created with your API key, sorted by most recent activity.

## Request

```bash theme={null}
GET /api/v1/tasks
Authorization: Bearer {api_key}
```

### Query Parameters

| Parameter | Type   | Default | Description                                 |
| --------- | ------ | ------- | ------------------------------------------- |
| `limit`   | number | 50      | Maximum number of tasks to return (max 100) |
| `offset`  | number | 0       | Number of tasks to skip (for pagination)    |

## Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "c37c1d78-4d23-4e53-949a-ddd775f25e01",
      "apiKeyId": "82344182-b81e-4f9a-8e7f-c14d8324caac",
      "username": "testuser",
      "sessionId": "80513b3f-9030-4776-a209-f2d96b1abce1",
      "conversationId": "1769442659997-70avfyadp",
      "status": "completed",
      "message": "What is 2+2?",
      "systemPrompt": null,
      "showInHistory": true,
      "autoExecute": true,
      "env": null,
      "error": null,
      "createdAt": "2026-01-26T15:50:54.870Z",
      "startedAt": "2026-01-26T15:50:59.998Z",
      "completedAt": "2026-01-26T15:56:03.070Z",
      "lastActivityAt": "2026-01-26T15:56:03.070Z",
      "messageCount": 2
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}
```

### Response Fields

Each task item includes all standard task fields plus enrichment fields:

| Field            | Type           | Description                                                                         |
| ---------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`             | string         | Unique task identifier                                                              |
| `apiKeyId`       | string         | ID of the API key used to create the task                                           |
| `username`       | string         | Username associated with the API key                                                |
| `sessionId`      | string         | ID of the agent session                                                             |
| `conversationId` | string         | ID of the conversation for history                                                  |
| `status`         | string         | Current task status                                                                 |
| `message`        | string         | Original task message                                                               |
| `systemPrompt`   | string \| null | Custom system prompt if provided                                                    |
| `showInHistory`  | boolean        | Whether task appears in conversation history                                        |
| `autoExecute`    | boolean        | Whether tools auto-execute                                                          |
| `env`            | object \| null | Non-sensitive env vars provided at creation                                         |
| `error`          | string \| null | Error message if task failed                                                        |
| `createdAt`      | string         | ISO timestamp when task was created                                                 |
| `startedAt`      | string \| null | ISO timestamp when execution started                                                |
| `completedAt`    | string \| null | ISO timestamp when task completed                                                   |
| `lastActivityAt` | string         | ISO timestamp of most recent activity (latest of completedAt, startedAt, createdAt) |
| `messageCount`   | number         | Number of messages in the conversation (0 if no conversation yet)                   |

### Pagination Object

| Field     | Type    | Description                               |
| --------- | ------- | ----------------------------------------- |
| `total`   | number  | Total number of tasks for this user       |
| `limit`   | number  | Number of tasks requested                 |
| `offset`  | number  | Number of tasks skipped                   |
| `hasMore` | boolean | Whether more tasks exist beyond this page |

### Task Status Values

| Status              | Description                    |
| ------------------- | ------------------------------ |
| `pending`           | Task created, not yet started  |
| `running`           | Task is currently executing    |
| `awaiting_approval` | Waiting for tool call approval |
| `completed`         | Task finished successfully     |
| `failed`            | Task failed with an error      |
| `cancelled`         | Task was cancelled             |

<Note>
  Tasks are sorted by `lastActivityAt` descending — the most recently active task appears first. This is ideal for building a conversation list sidebar. For real-time progress (`output`) or the final response, use [Get Task](/tasks/get). For real-time streaming, use [Stream Events](/tasks/stream).
</Note>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -s https://api.sigmic.ai/api/v1/tasks \
    -H "Authorization: Bearer sigmic_your_key_here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.sigmic.ai/api/v1/tasks', {
    headers: {
      'Authorization': 'Bearer sigmic_your_key_here'
    }
  });

  const { data: tasks, pagination } = await response.json();
  console.log(`Found ${pagination.total} tasks (showing ${tasks.length})`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.sigmic.ai/api/v1/tasks',
      headers={'Authorization': 'Bearer sigmic_your_key_here'}
  )

  result = response.json()
  tasks = result['data']
  pagination = result['pagination']
  print(f'Found {pagination["total"]} tasks (showing {len(tasks)})')
  ```
</CodeGroup>

### With Pagination

```bash theme={null}
# Get the second page of 10 tasks
curl -s "https://api.sigmic.ai/api/v1/tasks?limit=10&offset=10" \
  -H "Authorization: Bearer sigmic_your_key_here"
```

### Paginate All Tasks

```javascript theme={null}
async function getAllTasks(apiKey) {
  const tasks = [];
  let offset = 0;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `https://api.sigmic.ai/api/v1/tasks?limit=${limit}&offset=${offset}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const { data, pagination } = await response.json();
    tasks.push(...data);

    if (!pagination.hasMore) break;
    offset += limit;
  }

  return tasks;
}
```

## Errors

| Code              | Description                |
| ----------------- | -------------------------- |
| `AUTH_REQUIRED`   | No authentication provided |
| `INVALID_API_KEY` | Invalid or expired API key |