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

# List tasks

`GET /public-api/v1/tasks`

## Request

- Base URL: `https://app.hellobonsai.com`
- URL: `https://app.hellobonsai.com/public-api/v1/tasks`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.hellobonsai.com/oauth/authorize`
    - Token URL: `https://app.hellobonsai.com/oauth/token`
  - HTTP bearer

Lists tasks, a page at a time. Only active tasks come back unless you ask
for others with `filter[scope]`.

Descriptions are left out of list responses — retrieve a task on its own
to read `description_html` or `description_plain_text`.

Two keys depend on permissions and are left out entirely for a token
without them: `billable` for a token not allowed to see billing, and
`deal_id` for one not allowed to see deals. Treat both as optional keys
rather than assuming they are always there.

## Filtering

- `filter[assignee_id]` — one or more user ids, or `me` for whoever the
  token belongs to. Note this takes a user id, not a team member id.
- `filter[scope]` — which tasks to include: `active` (the default),
  `completed`, `archived`, `all`, `my_tasks`, `planned` (has a due date),
  `unplanned` (has none) or `upcoming_and_overdue`.
- `filter[due]` — a named date window: `today`, `overdue`,
  `today_or_overdue`, `this_week`, `this_month` or `upcoming`. Cannot be
  combined with `filter[due_from]` or `filter[due_to]`.
- `filter[due_from]` and `filter[due_to]` — an explicit date range.
  Either bound works on its own.
- `filter[billable]` — `true` for billable tasks, `false` for the rest.
  Tasks created before billing was tracked count as not billable. Needs
  permission to see billing; without it this filter returns `403`, since
  it would otherwise hand back the `billable` key that same token is
  not shown.
- `filter[deal_id]` — one or more deal ids. Needs permission to see
  deals; without it this filter returns `403` rather than quietly
  returning every task.
- `filter[priority]` — one or more of `urgent`, `high`, `medium`, `low`.
- `filter[project_id]` — one or more project ids.
- `filter[tag_id]` — one or more tag ids.
- `filter[task_status_id]` — one or more task status ids. This one also
  widens the default scope: tasks in the given columns come back whether
  they are active, completed or archived.
- `filter[title]` — searches task titles, ignoring case.

## Query parameters

- `page[number]` integer
- `page[size]` integer
- `filter[assignee_id]` string
- `filter[scope]` 'active' | 'completed' | 'archived' | 'all' | 'upcoming_and_overdue' | 'unplanned' | 'planned' | 'my_tasks'
- `filter[due]` 'today' | 'overdue' | 'today_or_overdue' | 'this_week' | 'this_month' | 'upcoming'
- `filter[due_from]` string, date
- `filter[due_to]` string, date
- `filter[billable]` 'true' | 'false'
- `filter[deal_id]` string
- `filter[priority]` string
- `filter[project_id]` string
- `filter[tag_id]` string
- `filter[task_status_id]` string
- `filter[title]` string

## Response `200`

A page of tasks, without their descriptions.

- object
  - `data` Task[], required
    - `uuid` string, uuid, nullable, required: Unique identifier for the task. This is the id every task endpoint takes in its path.
    - `title` string, nullable, required: Task title.
    - `number` string, nullable, required: Human-readable task reference. `null` until one has been assigned.
    - `due_date` string, date, nullable, required: Date the task is due, or `null` when it is unscheduled.
    - `start_date` string, date, nullable, required: Date work on the task starts, or `null` when unset.
    - `time_estimate_in_minutes` integer, nullable, required: Estimated effort in whole minutes, or `null` when no estimate is set.
    - `priority` 'urgent' | 'high' | 'medium' | 'low' | 'null', nullable, required: Priority bucket, or `null` when the task has no priority.
    - `completed_at` string, date-time, nullable, required: When the task was marked complete, or `null` while it is still open.
    - `archived_at` string, date-time, nullable, required: When the task was archived, or `null` while it is active.
    - `assignee_id` integer, nullable, required: User id of the assignee, or `null` when unassigned. Read-only — the create and update endpoints take `assignee_member_id` instead.
    - `assignee_member_id` integer, nullable, required: Team member id of the assignee, or `null` when unassigned. This is the value the create and update endpoints accept.
    - `creator_member_id` integer, nullable, required: Team member id of whoever created the task.
    - `project_id` integer, nullable, required: Id of the project the task belongs to, or `null` for a task that stands on its own.
    - `billable` boolean, nullable: Whether time logged against this task can be billed to the client. Absent unless the token is allowed to see billing.
    - `deal_id` integer, nullable: Id of the deal the task belongs to, or `null` when it is not attached to a deal. Absent unless the token is allowed to see deals.
    - `parent_task_uuid` string, nullable, required: `uuid` of this task's parent when it is a subtask, `null` for a top-level task.
    - `project_title` string, nullable, required: Title of the project the task belongs to, or `null`.
    - `assignee_member_name` string, nullable, required: Name of the assignee, or `null` when the task is unassigned.
    - `url` string, required: Absolute link to the task in the Bonsai app. Resolves to the task on its project board, or to the standalone task list when it belongs to no project.
    - `task_status` TaskStatus, required: A column of your task board. Moving a task between statuses is how you track its progress.
      - `id` string, uuid, required: Unique identifier for the status. Pass this value as `task_status_id` when creating or updating a task.
      - `status` string, required: Status name as it appears on the board.
      - `state` 'active' | 'complete', required: Whether tasks in this status count as open (`active`) or finished (`complete`).
      - `color` string, nullable, required: Hex color the status is drawn in, or `null` when it has none.
      - `position` integer, required: Position of the status on the board, ordered left to right.
    - `company_tags` CompanyTag[], required: Tags applied to the task. Only `id` and `name` are returned here — list the tags endpoint for a tag's type and color.
      - `id` integer, required: Unique identifier for the tag. Pass this value in `tag_ids` when tagging a task.
      - `name` string, required: Tag name as it appears in Bonsai.
  - `meta` PaginatedMeta, required: Metadata returned alongside every list response.
    - `request_id` string, required: Identifier for this request. Quote it when contacting support about a specific call.
    - `pagination` Pagination, required: Where the returned page sits in the full result set.
      - `page` integer, required: The page that was returned.
      - `page_size` integer, required: How many records this page can hold.
      - `has_more` boolean, required: Whether at least one more page follows this one. Keep incrementing `page[number]` while this is `true`.

## Other responses

- `400`: A filter key is unknown, a filter value is not allowed, two filters conflict, or a pagination parameter is not an integer.
- `401`: The access token is missing, expired or invalid.
- `403`: This token is not allowed to see tasks, used `filter[deal_id]` without permission to see deals, or `filter[billable]` without permission to see billing.
- `429`: Rate limit exceeded. Wait at least `Retry-After` seconds before trying again.

---

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