---
title: "List tasks."
method: GET
path: "/tasks"
tags: ["tasks"]
---

# List tasks.

`GET /tasks`

## Request

- Base URL: `https://restivity.ai/api/v1`
- URL: `https://restivity.ai/api/v1/tasks`
- Auth: OAuth 2 (authorization code, authorization URL `https://restivity.ai/oauth/authorize`, token URL `https://restivity.ai/api/oauth/token`, scopes: `tasks:read`)

Cursor-paginated list of the non-deleted tasks the caller can see (RLS): their own and their teammates' tasks in the projects they belong to — not only the tasks they created. Filter by `project_id` for one project's board.

## Query parameters

- `status` 'todo' | 'in_progress' | 'completed' | 'archived': Lifecycle state of a task.
- `priority` 'low' | 'medium' | 'high' | 'urgent'
- `project_id` string, uuid
- `is_for_today` union: Boolean: a JSON boolean, or the query-string literal "true" / "false".
  - boolean
  - 'true' | 'false'
- `is_important` union: Boolean: a JSON boolean, or the query-string literal "true" / "false".
  - boolean
  - 'true' | 'false'
- `is_urgent` union: Boolean: a JSON boolean, or the query-string literal "true" / "false".
  - boolean
  - 'true' | 'false'
- `cursor` string
- `limit` integer
- `sort_by` 'created_at' | 'updated_at' | 'due_date' | 'priority' | 'title' | 'code' | 'order'
- `sort_order` 'asc' | 'desc'
- `due_before` union: ISO 8601 date (YYYY-MM-DD) or full datetime with timezone offset, e.g. "2026-05-22" or "2026-05-22T00:00:00Z"
  - string, date
  - string, date-time
- `due_after` union: ISO 8601 date (YYYY-MM-DD) or full datetime with timezone offset, e.g. "2026-05-22" or "2026-05-22T00:00:00Z"
  - string, date
  - string, date-time
- `created_before` union: ISO 8601 date (YYYY-MM-DD) or full datetime with timezone offset, e.g. "2026-05-22" or "2026-05-22T00:00:00Z"
  - string, date
  - string, date-time
- `created_after` union: ISO 8601 date (YYYY-MM-DD) or full datetime with timezone offset, e.g. "2026-05-22" or "2026-05-22T00:00:00Z"
  - string, date
  - string, date-time
- `updated_before` union: ISO 8601 date (YYYY-MM-DD) or full datetime with timezone offset, e.g. "2026-05-22" or "2026-05-22T00:00:00Z"
  - string, date
  - string, date-time
- `updated_after` union: ISO 8601 date (YYYY-MM-DD) or full datetime with timezone offset, e.g. "2026-05-22" or "2026-05-22T00:00:00Z"
  - string, date
  - string, date-time
- `include_series` union: Default false: the list leaves out the template (master) of every `materialized` recurring series — its occurrences (one task per day, `parent_recurrence_id` = the master) are the tasks to do, and they are listed. true also returns the templates (to find a series and change its rule with `tasks_recurrence_update_rule`). A `reminder_only` recurring task is listed in every case: there the master is the task.
  - boolean
  - 'true' | 'false'

## Response `200`

Page of tasks.

- object
  - `data` Task[], required
    - `id` string, uuid, required
    - `user_id` string, uuid, required
    - `project_id` string, uuid, nullable, required
    - `title` string, required
    - `description` string, required: The stored HTML, as the task editor writes it (sanitized). To show it to a person read `description_text`.
    - `description_text` string, required: The description as plain text: every tag removed, one line per block, `- ` / `N. ` before list items, entities decoded — the same shape as a comment’s `content_text`. Show THIS to a person; `description` is the stored HTML. Read-only
    - `status` 'todo' | 'in_progress' | 'completed' | 'archived', required: Lifecycle state of a task.
    - `priority` 'low' | 'medium' | 'high' | 'urgent', required
    - `order` integer, nullable, required
    - `due_date` string, nullable, required
    - `is_for_today` boolean, required
    - `is_important` boolean, required
    - `is_urgent` boolean, required
    - `estimated_pomodoros` integer, required
    - `completed_pomodoros` integer, required
    - `is_recurring` boolean, required
    - `recurring_frequency` string, nullable, required
    - `recurring_end_date` string, nullable, required
    - `recurring_days` integer[], nullable, required
    - `parent_recurrence_id` string, uuid, nullable, required
    - `recurrence_model` 'materialized' | 'reminder_only', nullable, required
    - `recurrence_start_date` string, nullable, required: RES-115 — the series anchor ("Starts on") of a recurring master, a civil date at UTC midnight. The deadline is only a deadline: a `reminder_only` master's `due_date` is the occurrence it is currently on (it rolls forward when the occurrence is completed or skipped), a `materialized` master has none (each child occurrence carries its own). NULL on non-recurring rows and on child occurrences.
    - `completed_at` string, nullable, required
    - `assigned_to` string, uuid, nullable, required
    - `code` string, nullable, required
    - `created_at` string, required
    - `updated_at` string, required
    - `deleted_at` string, nullable, required
    - `url` string
    - `subtasks` Subtask[]
      - `id` string, uuid, required
      - `task_id` string, uuid, required
      - `title` string, required
      - `completed` boolean, required
      - `order` integer, nullable
      - `created_at` string
    - `tags` TagRef[]
      - `id` string, uuid, required
      - `user_id` string, uuid, required
      - `name` string, required
      - `color` string, required
      - `usage_count` integer, required
      - `deleted_at` string, nullable
    - `project` ProjectRef
      - `id` string, uuid, required
      - `name` string, required
      - `color` string, required
      - `prefix` string, nullable
      - `team_id` string, uuid, nullable
      - `team_name` string, nullable
      - `team_slug` string, nullable
    - `project_status` ProjectStatusRef
      - `id` string, uuid, required
      - `name` string, required
      - `color` string, required
      - `category` 'todo' | 'in_progress' | 'completed', required: Lifecycle category of a custom project status.
    - `assigned_to_profile` AssignedProfileRef
      - `id` string, uuid, required
      - `display_name` string, required
      - `photo_url` string, nullable, required
    - `planned_occurrences` PlannedOccurrence[]: AGF-381 — only on the master of a `materialized` series, from `tasks_get`: the next occurrences that do not exist yet (the nightly job creates each one 30 days before its day), up to the series end and at most 12, after the occurrences that already exist (those are real child tasks: `parent_recurrence_id` = this id). Absent on every other task and on list endpoints.
      - `date` string, required: The day of the occurrence (YYYY-MM-DD).
      - `creates_on` string, required: The day the nightly job creates it as a real task (YYYY-MM-DD): the date minus 30 days.
    - `series_change` SeriesChange
      - `change` 'to_reminder' | 'stop_repeating', required: `to_reminder`: the series is now a `reminder_only` master; `stop_repeating`: it is now a plain task.
      - `trashed_occurrence_ids` string[], required: The occurrences still to come (due today or later, not completed) — now in the Trash, restorable.
      - `kept_occurrence_ids` string[], required: The past and the completed occurrences — live, still linked to the series (`parent_recurrence_id`).
      - `reminder_due_date` string, nullable, required: `to_reminder`: the day the reminder is due (YYYY-MM-DD) — its next occurrence from today; null otherwise.
  - `next_cursor` string, nullable, required: Opaque cursor for the next page. `null` when this is the last page.

## Other responses

- `400`: Invalid request shape.
- `401`: Missing or invalid access token.
- `403`: Token lacks the required scope.
- `422`: Request body failed schema validation.
- `429`: Rate-limit exceeded for this tier.

---

[API](https://skmtc.dev/restivity/apis/restivity-rest-api.md) · [All operations](https://skmtc.dev/restivity/apis/restivity-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/restivity/apis/restivity-rest-api/revisions/5764e41ebb3a?raw)