Status
The status column represents a label designation for your item(s). It can be used to denote the status of a particular item, or hold any other labelling for the item. Each status column is a collection of indexes and their corresponding labels. Our API fully supports the status column, so you can filter, read, update, and clear it via the API.
Filtering the status column
Using the items_page
object, you can easily filter a board's items by specific columns or column values. The status column supports the any_of
, not_any_of
, is_empty
, and is_not_empty
operators.
It accepts the label's index as the compare_value
which you can find by querying the column's settings. You can also return blank values by sending 5
as the compare_value
.
Pro tip
items_page
is only available in API version2023-10
for now.
The following example returns all items on the specified board with a blank status value.
query {
boards (ids: 1234567890) {
items_page (query_params: {rules: [{column_id: "status", compare_value: [5], operator:any_of}]}) {
items {
id
name
}
}
}
}
Reading the status column
You can query the status column using the column_values
object. The object has different fields based on which API version you are using. Column values v2 fields will be available in API versions 2023-10
and later, while column values v1 fields are only supported in versions 2023-07
and 2023-04
.
Column values v2
The column_values
object enables you to return column-specific subfields by sending a fragment in your query. Values for the status column are of the StatusValue
type.
Pro tip
column_values
v2 fields are only available in API version2023-10
.
query {
items (ids:[1234567890, 9876543210]) {
column_values {
... on StatusValue {
index
value
}
}
}
}
Fields
Field | Description |
---|---|
column Column! | The column the value belongs to. |
id ID! | The column's unique identifier. |
index Int | The column's status index in the board. |
is_done Boolean | Whether or not the item's status is done. |
label String | The column's status label value. |
label_style StatusLabelStyle | The status label's style. |
text String | The column's value as text. |
type ColumnType! | The column's type. |
update_id ID | The unique identifier of the update attached to the column's status. |
updated_at Date | The column's last updated date. |
value JSON | The column's JSON-formatted raw value. |
Column values v1
You can return the data in a status column in two different formats. The text field will return the data as a simple string, and the value field will return the data as a JSON string.
Removing column values v1 support
column_values
v1 fields will no longer be supported in API versions2023-10
and later.
{
"text": "Working on it",
"value": "{\"index\":0,\"post_id\":null,\"changed_at\":\"2021-07-21T12:00:00.000Z\"}"
}
Updating the status column
You can update a status column with both a simple string and a JSON string. The status column has a limit of 40 labels.
You can update a status column using the change_simple_column_value
mutation and sending a simple string in the value
argument. You can also use the change_multiple_column_values
mutation and pass a JSON string in the column_values
argument. Please note that status columns have a limit of 40 labels.
Simple strings
To update a status column, send the index of the status you want to set. If you don’t know the index of the label you’re trying to set, you can send the label instead. If you don't specify create_labels_if_missing: true
in your query, the labels you send that don't exist already will not get created and your query will get an error containing all the existing labels and their indexes.
mutation {
change_simple_column_value (item_id:9876543210, board_id:1234567890, column_id:"status", value: "8") {
id
}
}
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
query : "mutation ($myBoardId:Int!, $myItemId:Int!, $myColumnValue: String!, $columnId: String!) { change_simple_column_value (item_id:$myItemId, board_id:$myBoardId, column_id: $columnId, value: $myColumnValue) { id } }",
variables : JSON.stringify({
myBoardId: 1234567890,
myItemId: 9876543210,
columnId: "status",
myColumnValue: "8"
})
})
})
JSON
To update a status column with a JSON string, send the index of the status you want to set. If you don’t know the index of the label you’re trying to set, you can send the label instead. If you don't specify create_labels_if_missing: true
in your query, the labels you send that don't exist already on the board will not get created, and your query will get an error containing all the existing labels and their indexes. Check out this mutation in action in our Postman library or follow along with these code samples!
mutation {
change_multiple_column_values(item_id:9876543210, board_id:1234567890, column_values: "{\"status\" : {\"label\" : \"Done\"}}") {
id
}
}
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
query : "mutation ($myBoardId:Int!, $myItemId:Int!, $myColumnValues:JSON!) { change_multiple_column_values(item_id:$myItemId, board_id:$myBoardId, column_values: $myColumnValues) { id }}",
variables : JSON.stringify({
myBoardId: 1234567890,
myItemId: 9876543210,
myColumnValues: "{\"status\" : {\"label\" : \"Done\"}}"
})
})
})
Clearing the status column
You have two options to clear a status column. First, you can use the change_multiple_column_values
mutation and pass null
an empty string, or an empty object in the column_values
argument. Check out this mutation in action in our Postman library or follow along with these code samples!
mutation {
change_multiple_column_values(item_id:9876543210, board_id:1234567890, column_values: "{\"status\" : null}") {
id
}
}
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
query : "mutation ($myBoardId:Int!, $myItemId:Int!, $myColumnValues:JSON!) { change_multiple_column_values(item_id:$myItemId, board_id:$myBoardId, column_values: $myColumnValues) { id } }",
variables : JSON.stringify({
myBoardId: 1234567890,
myItemId: 9876543210,
myColumnValues: "{\"date\" : null}"
})
})
})
You can also use the change_simple_column_value
mutation and pass an empty string in the value
argument.
mutation {
change_simple_column_value(item_id:9876543210, board_id:1234567890, column_id: "status", value: "") {
id
}
}
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
query : "mutation ($myBoardId:Int!, $myItemId:Int!, $myColumnValue: String!, $columnId: String!) { change_simple_column_value (item_id:$myItemId, board_id:$myBoardId, column_id: $columnId, value: $myColumnValue) { id } }",
variables : JSON.stringify({
myBoardId: 1234567890,
myItemId: 9876543210,
columnId: "status",
myColumnValue: ""
})
})
})
Index values and color mapping
As mentioned above, you can use both Index and Label values when using JSON formatting in your Mutation calls to update the Status column.
change_column_value
change_multiple_column_values
create_item
,create_subitem
By default, every index value matches a specific color. For example, the Green status has the index 1. Here's a full list of the indexes and matching values.
When you create a new Status label, it will follow the default index value and its index will not change. However, the color of a status label can be changed. Therefore, you cannot assume a label’s color and index will always match.
Take the following example:
Index: 2
will have a color value of #e2445c
. Thus, using this index value will set the Status column value to a Red-shadow color, as shown below:

And on the board, this will appear as such:
The color values are not static and can be changed within the Status column labels. You can find more info on this here.
Then, the index value will remain the same, but the color value will be changed. For example, if I chose Black as the new color, this is how the color value would appear in the API:
And this is how the item would appear on the board:
As such, using index values does not guarantee that you will populate the same color values across multiple boards.
If you encounter a mismatch of index values when sending data between boards in your account, we recommend changing the color of the labels back to the default values manually.
Join our developer community!
We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎
Updated about 1 month ago