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

# Listing tasks

> Page, filter, and sort your organization's Tasks with GET /task/list — the basis for dashboards and reconciliation.

## When to list Tasks

`GET /task/list` returns your organization's Tasks as a paginated, filtered, and
sorted collection. Reach for it whenever you need more than a single Task by ID:

* **Dashboards** — show every Task created today, or everything currently
  `waiting` on input.
* **Reconciliation** — sweep the Tasks you created in a date window and match them
  back to your own records by `external_id`, catching anything you missed a
  callback for.

The list is always scoped to the organization behind your bearer token; you never
see another org's Tasks.

## The response shape

The endpoint returns a `GetTasksResponse`:

| Field    | Type                   | Description                                                                                                                           |
| -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `count`  | integer                | Total number of Tasks matching your filters — **not** the number returned in this page. Use it to compute how many more pages remain. |
| `offset` | integer                | The start offset this page was read from (echoes your request).                                                                       |
| `tasks`  | array of `TaskSummary` | The matching Tasks for this page.                                                                                                     |

Each `TaskSummary` carries the Task's metadata — `uuid`, `external_id`,
`task_type`, `status`, `name`, `cleared`, `created`, and `latest_status_change`.
It is the summary shape, not the full `TaskDetails`; fetch a single Task with
[`GET /task/get`](/guides/async-results) when you need its `data_items`,
`verdicts`, or `issues`.

## Pagination

Page through results with `offset` and `length`:

| Parameter | Default | Bounds    | Description                                        |
| --------- | ------- | --------- | -------------------------------------------------- |
| `offset`  | `0`     | `>= 0`    | Zero-based index of the first record to return.    |
| `length`  | `100`   | `1`–`200` | Maximum number of records to return from `offset`. |

Walk the pages by advancing `offset` by `length` until you have collected `count`
Tasks.

<Note>
  An `offset` past the end of the result set is **not** an error. The API returns
  `200 OK` with your requested `offset` echoed back and an **empty** `tasks` list.
  Loop until `tasks` comes back empty, or until `offset >= count`.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -G "https://app.synthpop.ai/public/v1/task/list" \
    -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN" \
    --data-urlencode "offset=0" \
    --data-urlencode "length=100"
  ```

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

  BASE_URL = "https://app.synthpop.ai/public/v1"


  def list_all_tasks(jwt_token: str, **filters) -> list[dict]:
      headers = {"Authorization": f"Bearer {jwt_token}"}
      tasks: list[dict] = []
      offset, length = 0, 200  # max page size
      while True:
          resp = requests.get(
              f"{BASE_URL}/task/list",
              headers=headers,
              params={"offset": offset, "length": length, **filters},
          )
          resp.raise_for_status()
          body = resp.json()
          tasks.extend(body["tasks"])
          offset += length
          if offset >= body["count"] or not body["tasks"]:
              return tasks
  ```
</CodeGroup>

## Filtering

Combine any of these query parameters; they are ANDed together.

| Parameter       | Type                  | Description                                                                                          |
| --------------- | --------------------- | ---------------------------------------------------------------------------------------------------- |
| `status`        | array of `TaskStatus` | Return only Tasks whose status is one of the given values. Repeat the parameter for multiple values. |
| `task_type`     | array of string       | Return only Tasks of the given task types. Repeat for multiple values.                               |
| `cleared`       | boolean               | Filter on whether the `cleared` flag is set (`true`) or unset (`false`). Omit to include both.       |
| `date_from`     | date or date-time     | Return Tasks whose selected date is newer than this value.                                           |
| `date_to`       | date or date-time     | Return Tasks whose selected date is up to and including this value.                                  |
| `selected_date` | `DateFlavor`          | Which date `date_from`/`date_to` filter on. See below. Defaults to `created`.                        |

`status` accepts the wire `TaskStatus` values: `pending`, `processing`,
`waiting`, `completed`, `failed`, `invalid`.

<Note>
  `cleared` is asymmetric. You **set** `cleared` with a boolean via update; it
  **reads back** as the timestamp it was set at (or `null`). So the list filter
  and `TaskSummary.cleared` you get back is a timestamp (or `null`), while the
  filter parameter above takes a boolean presence check.
</Note>

`selected_date` (`DateFlavor`) chooses which timestamp the date window applies to:

| `DateFlavor`           | Filters on                              |
| ---------------------- | --------------------------------------- |
| `created` (default)    | When the Task was created.              |
| `latest_status_change` | When the Task last changed status.      |
| `cleared`              | When the Task's `cleared` flag was set. |

```bash cURL theme={null}
# Everything still waiting on input, created since the start of the month
curl -s -G "https://app.synthpop.ai/public/v1/task/list" \
  -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN" \
  --data-urlencode "status=waiting" \
  --data-urlencode "selected_date=created" \
  --data-urlencode "date_from=2026-07-01"
```

## Sorting

| Parameter        | Default   | Description                                                                                                 |
| ---------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `order_by`       | `created` | The `OrderBy` key to sort on: `created`, `latest_status_change`, `cleared`, `name`, `id`, or `external_id`. |
| `sort_ascending` | `false`   | `true` sorts ascending; `false` (or omitted) sorts **descending**.                                          |

```bash cURL theme={null}
# Oldest-first by creation date
curl -s -G "https://app.synthpop.ai/public/v1/task/list" \
  -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN" \
  --data-urlencode "order_by=created" \
  --data-urlencode "sort_ascending=true"
```

<Tip>
  For stable reconciliation runs, sort by a fixed key (e.g. `order_by=created`
  with `sort_ascending=true`) and page all the way to `count`. Because the default
  sort is descending, newly created Tasks appear on the first page — handy for a
  "latest activity" dashboard, but shift results underneath you mid-run, so pin
  the sort and, if needed, a `date_to` upper bound.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="Working with async results" icon="rotate" href="/guides/async-results">
    Fetch and poll a single Task once you have its ID.
  </Card>

  <Card title="Tasks" icon="list-check" href="/concepts/tasks">
    The Task resource and its status lifecycle.
  </Card>
</CardGroup>