The status column represents a label designation for your item(s). It's commonly used to track project progress, item states, or any custom labeling system. Each status column contains a collection of indexes with corresponding labels and colors.

The API allows you to read, filter, create, update, and clear status columns across your monday.com boards.

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 status columns using either simple strings or JSON strings. Each status column can have a maximum of 40 labels. When updating, you can use either the index value or the label text.

Using index vs label values

• Index values (recommended): Numeric identifiers that remain consistent regardless of label text changes
• Label values: The actual text displayed, but may be ambiguous if labels contain numbers

Important: If a label is purely numeric (like "2023" or "100"), you must use the index value instead of the label text to avoid conflicts.

Simple string updates

Using the change_simple_column_value mutation, you can pass either the index or the label value of the status you want to update 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
  }
}

JSON updates

Using the change_multiple_column_values mutation, you can update multiple columns at once.

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 values and color mapping

Understanding the relationship between index values, labels, and colors is crucial for working with status columns effectively.

Default index and color mapping

Every status column starts with default index values that correspond to specific colors. Here are the most common default mappings:

View the complete list of default index values and colors.

Important considerations

While index values remain constant, users can change the colors and labels associated with them. For example:

• Index 1 might start as "Done" with green color
• A user could change it to "Completed" with blue color
• The index remains 1, but the appearance changes

When working across multiple boards, do not assume that the same index will have the same color or label. Each board can have different customizations.

Best Practice: Query the column settings to get current label and color mappings before making assumptions:

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

When to use index vs label

• Use index values when you need consistency across different boards or when labels might change
• Use label values when working within a single board and you want human-readable updates
• Always use index values when the label text is purely numeric