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.

Read a status column

You can query status columns using the column_values object that enables you to return column-specific subfields by sending a fragment in your query.

Before working with status columns, it's important to understand that the API returns different value types depending on your board type:

• Classic boards: Status columns return StatusValue type
• Multi-level boards: Status rollup columns return 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
        }
      }
    }
  }
}

StatusValue Fields

You can use the following fields to specify what information to return.

BatteryValue (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 {
          count
          key
        }
      }
    }
  }
}

BatteryValue Fields

Filter a status column

Using the items_page object, you can filter a board's items by specific status values.

Filter Options

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

Create a status column

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

Arguments

Update a status column

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 a status column

You have several options to clear a status column value.

Using change_multiple_column_values

Pass null, an empty string, or an empty object in the column_values argument:

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

Using change_simple_column_value

Pass an empty string in the value argument:

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "status"
    value: ""
  ) {
    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