Listing tasks

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 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.

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.

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"

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

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.

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.

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.

cURL

# 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.

cURL

# 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"

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.

Working with async results

Fetch and poll a single Task once you have its ID.

Tasks

The Task resource and its status lifecycle.

Get started

Core concepts

Working with the API

Referral & order intake

Coverage & authorization

Patient engagement

Resources

Support

When to list Tasks

The response shape

Filtering

Sorting

Working with async results

Tasks

​When to list Tasks

​The response shape

​Pagination

​Filtering

​Sorting

​Related

Working with async results

Tasks

When to list Tasks

The response shape

Pagination

Filtering

Sorting

Related