The status column displays labels that represent the state of an item. It’s commonly used for workflows, project progress, and visual status reporting. Each status column contains a set of labels, colors, and indexes.

Via the API, the status column supports read, filter, create, update, and clear operations.

Column Type	Implementation Type	Supported Operations
`status`	`StatusValue`	Read: Yes Filter: Yes Create" Yes Update: Yes Clear: Yes

Queries

Status columns can be queried through the column_values field on items using an inline fragment.

Depending on the board type, the API returns one of two value types:

Classic boards: StatusValue type
Multi-level boards: BatteryValue type

This affects how you query and interpret the data, as shown in the examples below.

StatusValue (Classic Boards)

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on StatusValue {
        id
        index
        label
        text
        is_done
        label_style {
          color
          is_done
        }
      }
    }
  }
}

Fields

You can use the following fields to specify what information your StatusValue implementation will return.

Field	Description
column `Column!`	The column the value belongs to.
id `ID!`	The column's unique identifier.
index `Int`	The status index value (used for updates).
is_done `Boolean`	Whether the status is marked as complete.
label `String`	The current label displayed for the item.
label_style `StatusLabelStyle`	The label's color and styling information.
text `String`	The column's value as text. Returns `null` if the column has an empty value.
type `ColumnType!`	The column's type.
update_id `ID`	The update associated with this status (if any).
updated_at `Date`	The column's last updated date.
value `JSON`	The column's JSON-formatted raw value.

BatteryValue (Multi-Level Boards)

Returned for status rollups on multi-level boards. This type aggregates status values from sub-items, showing counts for each status type.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on BatteryValue {
        id
        text
        battery_value {
          key
          count
        }
      }
    }
  }
}

Fields

You can use the following fields to specify what information your BatteryValue implementation will return.

Field	Description	Supported Fields
battery_value `[BatteryValueItem!]!`	The column's indices and number of occurrences.	count `Int!` key `ID!`
column `Column!`	The column the value belongs to.
id `ID!`	The column's unique identifier.
text `String`	The column's value as text. Returns `null` if the column has an empty value.
type `ColumnType!`	The column's type.
value `JSON`	The column's JSON-formatted raw value.

Filter

You can filter items by status values using the items_page object. The filters support matching by:

Label ID (recommended)
Label text (contains_terms)
Empty values

Compare Values	Description	Operators
The label's ID	Items with a specific label ID. Label IDs can be found by querying the column's settings.	`any_of`: returns items with the specified ID `not_any_of`: excludes items with the specified ID
The label's text (as a string)	Items with a specific label.	`contains_terms`: returns items with the specified text value
`5`	Represents items with empty status values. Empty labels currently use ID `5` by default.	`any_of`: returns items with empty values `not_any_of`: returns items without empty values
`[]`	Items with empty values.	`is_empty`: returns items with empty values `is_not_empty`: returns items without empty values

Examples

Filter by empty status

This example returns all items on the specified board with an empty status value.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "status"
            compare_value: [5]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Filter by status label

This example returns all items on the specific board with a "Done" label.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "status"
            compare_value: "Done"
            operator: contains_terms
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on StatusValue {
            label
          }
        }
      }
    }
  }
}

Mutations

Create

Required scope: boards:write

The create_status_column mutation creates a new status column with strongly typed settings via the API. You can specify which fields to return in the mutation response.

mutation {
  create_status_column(
    board_id: 1234567890
    id: "project_status"
    title: "Project Status"
    defaults: {
      labels: [
        { color: working_orange, label: "On Hold", index: 2}
        { color: done_green, label: "Done", index: 1}
        { color: sky, label: "Working On It", index: 3}
      ]
    },
    description: "The project's status."
  ) {
    description
    id
    title
    settings_str
  }
}

Update

You can update a status column using change_simple_column_value or change_multiple_column_values. You can send values as simple strings or JSON objects, depending on the mutation you choose.

Each status column can contain up to 40 labels.

You may update the column using either:

Index values: stable and recommended, especially when working across multiple boards
Label text: human-readable, but fragile if labels change

🚧
If a label is numeric (e.g., “2023”), always update by index, not label.

`change_simple_column_value`

Pass either the index or the label value in the value argument.

Update by index

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "status"
    value: "1"
  ) {
    id
    name
  }
}

Update by label Text

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "status"
    value: "Done"
    create_labels_if_missing: true
  ) {
    id
    name
  }
}

`change_multiple_column_values`

Send the index or label keys as a JSON object in column_values.

Update by index (JSON)

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"status\": {\"index\": 1}}"
  ) {
    id
    name
  }
}

Update by label (JSON)

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"status\": {\"label\": \"Done\"}}"
    create_labels_if_missing: true
  ) {
    id
    name
  }
}

Clear

You can clear a status column using change_simple_column_value or change_multiple_column_values.

`change_simple_column_value`

Pass an empty string in value.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "status"
    value: ""
  ) {
    id
    name
  }
}

`change_multiple_column_values`

Pass null or an empty string/object in column_values.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"status\": null}"
  ) {
    id
    name
  }
}

Index and Color Mapping

Status columns use index values to identify each label. Each index corresponds to a label and color, and these mappings can be customized per board.

Below are monday.com’s default mappings:

Index	Default Label	Default Color	Color Code
0	(Empty/Blank)	Gray	#c4c4c4
1	Done	Green	#00c875
2	Working on it	Orange	#fdab3d
3	Stuck	Red	#e2445c
4	(Custom)	Blue	#0086c0
5	(Empty)	Gray	#c4c4c4

View the complete list of default index values and colors.

Important considerations

While index values are stable, the label text and colors are customizable. That means the mapping of each index can differ between boards.

For example:

Index 1 might begin as the green "Done" label
A board admin changes it to blue "Completed"
The index remains 1, but the display label and color change

Do not assume that the same index corresponds to the same label or color on every board. Always check the board’s configuration with the following query:

query {
  boards(ids: 1234567890) {
    columns(ids: ["status"]) {
      id
      title
      settings_str
    }
  }
}