---
title: "List task statuses"
method: GET
path: "/public-api/v1/task_statuses"
tags: ["Task Statuses"]
---

# List task statuses

`GET /public-api/v1/task_statuses`

## Request

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

Lists the columns of your task board — `To Do`, `In Progress` and `Done`,
plus any columns your account has added.

This is where you turn a status name into the `task_status_id` the task
endpoints take, whether you are placing a new task in a column, moving
an existing one, or filtering a list by column.

## Query parameters

- `page[number]` integer
- `page[size]` integer

## Response `200`

A page of task statuses, ordered by their position on the board.

- object
  - `data` TaskStatus[], required
    - `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.
  - `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 pagination parameter is not an integer.
- `401`: The access token is missing, expired or invalid.
- `403`: This token is not allowed to see tasks, so it cannot read the board columns either.
- `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)