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

# List tasks

`GET /tasks`

## Request

- Base URL: `https://tasg.app/api/v1`
- URL: `https://tasg.app/api/v1/tasks`
- Auth: HTTP bearer

Tasks in projects the caller belongs to, ordered by `position`. Pass `exclude_completed=true` and read `total` to answer "how many open" questions in one call.

## Query parameters

- `project_id` string, uuid
- `workspace_id` string, uuid
- `assignee_id` string, uuid
- `status` 'not_started' | 'in_progress' | 'blocked' | 'completed'
- `priority` 'none' | 'low' | 'medium' | 'high' | 'urgent'
- `due_before` string, date
- `due_after` string, date
- `include_subtasks` 'true' | 'false'
- `exclude_completed` 'true' | 'false'
- `search` string
- `page` integer
- `per_page` integer

## Response `200`

A page of tasks.

- object
  - `tasks` Task[], required
    - `id` string, uuid, required
    - `title` string, required
    - `description` string, nullable
    - `parent_task_id` string, uuid, nullable
    - `parent_task` object, nullable
      - `id` string, uuid, required
      - `title` string, required
    - `created_via` string: Which surface created the task: `app`, `mcp`, `assistant`, `api` …
    - `ai_touched_at` string, date-time, nullable: Last time an AI agent created or edited this task.
    - `nesting_level` integer: 0 = top-level; subtasks may nest 5 deep.
    - `position` number: Sort key within the section (ascending).
    - `primary_project_id` string, uuid, required
    - `section_id` string, uuid, nullable
    - `assignee_id` string, uuid, nullable
    - `assignee` object, nullable
      - `id` string, uuid, required
      - `full_name` string, required
      - `avatar_url` string, uri, nullable
    - `created_by` string, uuid
    - `creator` object, nullable
      - `id` string, uuid, required
      - `full_name` string, required
      - `avatar_url` string, uri, nullable
    - `start_date` string, date, nullable: Calendar date, YYYY-MM-DD
    - `due_date` string, date, nullable: Calendar date, YYYY-MM-DD
    - `due_date_type` 'fixed' | 'relative': `relative` tasks derive their due date from another task plus an offset.
    - `relative_offset_days` integer, nullable
    - `relative_offset_from_task_id` string, uuid, nullable
    - `recurrence` 'daily' | 'weekly' | 'fortnightly' | 'monthly', nullable
    - `next_occurrence_id` string, uuid, nullable: Set once this completion has spawned the next occurrence of a recurring task.
    - `completed_at` string, date-time, nullable
    - `category` string, nullable
    - `priority` 'none' | 'low' | 'medium' | 'high' | 'urgent', required
    - `status` 'not_started' | 'in_progress' | 'blocked' | 'completed', required: Lifecycle state. `blocked` is set automatically while a dependency is incomplete.
    - `subtask_count` integer
    - `comment_count` integer
    - `attachment_count` integer
    - `blocked_by_count` integer: Dependencies this task waits on.
    - `blocking_count` integer: Tasks waiting on this one.
    - `tags` Tag[]
      - `id` string, uuid, required
      - `name` string, required
      - `color` string, required: Hex colour, e.g. `#3b82f6`.
    - `watchers` object[]
      - `user_id` string, uuid, required
      - `full_name` string, required
      - `avatar_url` string, uri, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `total` integer, required
  - `page` integer, required
  - `per_page` integer, required

## Other responses

- `400`: Validation failed: the body or query did not match the schema, or a business rule was violated. `error` says which.
- `401`: Missing, invalid, expired or revoked credentials.
- `403`: Authenticated, but not allowed: not a member, insufficient project role or the API token lacks the required scope.
- `429`: Rate limited. Back off and retry after the window in the `RateLimit-*` headers.

---

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