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.

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.

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.

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

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:

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
    }
  }
}