---
title: "List board groups"
method: GET
path: "/public-api/v1/board_groups"
tags: ["Board Groups"]
---

# List board groups

`GET /public-api/v1/board_groups`

## Request

- Base URL: `https://app.hellobonsai.com`
- URL: `https://app.hellobonsai.com/public-api/v1/board_groups`
- 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 stages of your deal and project boards, a page at a time.

Deals move through these stages, so this is where you turn a stage name
such as `Won` into the `board_group_id` the deal endpoints take.

You only get the boards you are allowed to list: deal stages need
permission to see deals, project stages need permission to see
projects. Without either, the list comes back empty.

## Filtering

- `filter[name]` — partial, case-insensitive match on the stage name.
- `filter[resource_type]` — `Deal` or `Project`, to return one board's
  stages only. Omit it to get both.

## Query parameters

- `page[number]` integer
- `page[size]` integer
- `filter[name]` string
- `filter[resource_type]` 'Deal' | 'Project'

## Response `200`

A page of pipeline stages, grouped by board and ordered by their position on it.

- object
  - `data` BoardGroup[], required
    - `id` string, uuid, required: Unique identifier for the stage. Pass this value as `board_group_id` when creating or updating a deal.
    - `name` string, required: Stage name as it appears on the board.
    - `color` string, required: Hex color the stage is drawn in.
    - `position` integer, required: Position of the stage on its board, ordered left to right.
    - `state` 'active' | 'complete', required: Whether the stage holds work in progress (`active`) or is a closed-out stage (`complete`).
    - `deal_probability` string, nullable, required: Default win probability applied to deals that reach this stage, as a decimal string percentage.
    - `resource_type` 'Deal' | 'Project', required: Which pipeline the stage belongs to — the deal board or the project board.
  - `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, or `filter[resource_type]` is not `Deal` or `Project`.
- `401`: The access token is missing, expired or invalid.
- `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)