Learn how to read and update columns on monday boards using the platform API
monday.com boards are formatted as a table with columns and rows of items. Each column has specific functionality and only stores relevant data. For example, a numbers column will store numerical values, a text column will store text values, and a time tracking column will store only time-based data based on log events.
Queries
You can retrieve monday.com board column data via the API through the columns
query.
- Required scope:
boards:read
- Returns an array containing metadata about one or a collection of columns
- Can only be nested within another query (e.g.,
boards
); can't be queried directly at the root
query {
boards (ids: 1234567890) {
columns {
id
title
}
}
}
import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `query ($board: [ID!]) {boards (ids: $board) { columns { id title }}}`
const variables = {
board: 1234567
}
const response = await mondayApiClient.request(query, variables);
Arguments
You can use the following arguments to reduce the number of results returned in your columns
query.
Argument | Description |
---|---|
ids [String] | The specific columns to return. Please use quotation marks when passing this ID as a string. |
types [ColumnType!] | The specific type of columns to return. |
Fields
You can use the following fields to specify what information your columns
query will return.
Field | Field Description |
---|---|
archived Boolean! | Returns true if the column is archived. |
capabilities ColumnCapabilities! | Calculates and retrieves the column's rollup value. Only available in API versions 2025-10 and later. |
description String | The column's description. |
id ID! | The column's unique identifier. |
revision String! | The column's current revision. Used for optimistic concurrency control. Only available in API versions 2025-10 and later. |
settings JSON | The column's dynamic JSON settings. For multi-level boards, use this field to retrieve labels and color mappings for status rollup columns. Only available in API versions 2025-10 and later. |
settings_str String! | The column's settings. Deprecated in API versions 2025-10 and later. Use settings instead. |
title String! | The column's title. |
type ColumnType! | The column's type. |
width Int | The column's width. |
Mutations
Create a column
Required scope: boards:write
The create_column
mutation creates a new column on a board within the account via the API. You can specify which fields to return from the new column in the mutation response.
mutation{
create_column(board_id: 1234567890, title:"Work Status", description: "This is my work status column", column_type:status) {
id
title
description
}
}
import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($board: ID!, $title: String!, $desc: String!) { create_column(board_id: $board, title: $title, description: $desc, column_type:status){ id title description}}`
const variables = {
board: 1234567,
title: "Work status",
desc: "Current status of the task"
}
const response = await mondayApiClient.request(query, variables);
Arguments
You can use the following arguments to define the new column's characteristics.
Argument | Description | Supported Fields |
---|---|---|
after_column_id ID | The unique identifier of the column after which the new column will be created. | |
board_id ID! | The unique identifier of the board where the new column should be created. | |
capabilities ColumnCapabilitiesInput | The new column's capabilities configuration. If omitted, defaults apply: on multi-level boards, numeric, date, timeline, and status columns are created with the calculated capability enabled; in all other cases, no capabilities are applied. To override this default on multi-level boards, pass an empty argument to create the column without capabilities.Only available in API versions 2025-10 and later. | |
column_type ColumnType! | The type of column to create. This determines which properties are valid in the defaults argument. | |
defaults JSON | The new column's defaults. Accepts a JSON object or string. Validated against the column-type schema; query get_column_type_schema to see available properties. | |
description String | The new column's description. | |
id String | The column's user-specified unique identifier. If not provided, a new ID will be auto-generated. If provided, it must meet the following requirements: - [1-20] characters in length (inclusive) - Only lowercase letters (a-z) and underscores (_) - Must be unique (no other column on the board can have the same ID) - Can't reuse column IDs, even if the column has been deleted from the board - Can't be null, blank, or an empty string | |
title String! | The new column's title. |
Create dropdown column
Required scope: boards:write
The create_dropdown_column
mutation creates a new dropdown column with strongly typed settings via the API. You can specify which fields to return from the new dropdown column in the mutation response.
mutation {
create_dropdown_column(
board_id: 1234567890,
id: "project_category",
title: "Project Category",
defaults: {
label_limit_count: 1,
limit_select: true,
labels: [
{label: "HR"},
{label: "R&D"},
{label: "IT"}
]
},
description: "The project's category."
) {
description
id
title
}
}
Arguments
You can use the following arguments to define the new dropdown column's characteristics.
Argument | Description | Supported Fields |
---|---|---|
after_column_id ID | The unique identifier of the column after which the new dropdown column will be created. | |
board_id ID! | The unique identifier of the board where the new dropdown column should be created. | |
defaults CreateDropdownColumnSettingsInput | The new dropdown column's settings. | labels [CreateStatusLabelInput!]! |
description String | The new dropdown column's description. | |
id String | The dropdown column's user-specified unique identifier. If not provided, a new ID will be auto-generated. If provided, it must meet the following requirements: - [1-20] characters in length (inclusive) - Only lowercase letters (a-z) and underscores (_) - Must be unique (no other column on the board can have the same ID) - Can't reuse column IDs, even if the column has been deleted from the board - Can't be null, blank, or an empty string | |
title String! | The new dropdown column's title. |
Create 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 from the new status column 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
}
}
Arguments
You can use the following arguments to define the new status column's characteristics.
Argument | Description | Supported Fields |
---|---|---|
after_column_id ID | The unique identifier of the column after which the new status column will be created. | |
board_id ID! | The unique identifier of the board where the new status column should be created. | |
capabilities StatusColumnCapabilitiesInput | The new status column's capabilities configuration. If omitted, defaults apply: on multi-level boards, numeric, date, timeline, and status columns are created with the calculated capability enabled. To override this default on multi-level boards, pass an empty argument to create the column without capabilities. | calculated StatusCalculatedCapabilityInput |
defaults CreateStatusColumnSettingsInput | The new status column's settings. | labels [CreateStatusLabelInput!]! |
description String | The new status column's description. | |
id String | The status column's user-specified unique identifier. If not provided, a new ID will be auto-generated. If provided, it must meet the following requirements: - [1-20] characters in length (inclusive) - Only lowercase letters (a-z) and underscores (_) - Must be unique (no other column on the board can have the same ID) - Can't reuse column IDs, even if the column has been deleted from the board - Can't be null, blank, or an empty string | |
title String! | The new status column's title. |
Change column value
Required scope: boards:write
The change_column_value
mutation changes the value of a column in a specific item (row) with a JSON value via the API. You can also specify what fields to query back when you run the mutation.
For multi-level boards, rollup column changes are blocked if the item has at least one subitem.
mutation {
change_column_value (board_id: 1234567890, item_id: 9876543210, column_id: "email9", value: "{\"text\":\"[email protected]\",\"email\":\"[email protected]\"}") {
id
}
}
import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($board_id: ID!, $item_id: ID!, $column_id: String!, $column_value: JSON!) { change_column_value (board_id: $board_id, item_id: $item_id, column_id: $column_id, value: $column_value) {id}}`;
const variables = {
board_id: 9571351437,
item_id: 9571351485,
column_id: "email_mksr9hcd", // email column
column_value: JSON.stringify({
text: "Dabba Baz",
email: "[email protected]",
})
};
const response = await mondayApiClient.request(query, variables);
Arguments
You can use the following arguments to define which column to change and its new value.
Argument | Description |
---|---|
board_id ID! | The unique identifier of the board that contains the column to change. |
column_id String! | The column's unique identifier. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing. Requires permission to change the board structure. |
item_id ID | The unique identifier of the item to change. |
value JSON! | The new value of the column in JSON format. See Column Types Reference for each column type and their format. |
Change a simple column value
Required scope: boards:write
The change_simple_column_value
mutation changes the value of a column in a specific item (row) with a string value via the API. Each column has a certain type, and different column types expect a different set of parameters to update their values. You can specify which fields to return in the mutation response.
mutation {
change_simple_column_value (board_id: 1234567890, item_id: 9876543210, column_id: "status", value: "Working on it") {
id
}
}
import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($board_id: ID!, $item_id: ID!, $column_id: String!, $column_value: String!) { change_simple_column_value (board_id: $board_id, item_id: $item_id, column_id: $column_id, value: $column_value) {id}}`;
const variables = {
board_id: 9571351437,
item_id: 9571351485,
column_id: "email_mksr9hcd",
// Each column type has a different value structure
// Check "Column types reference" section for different values
column_value: "[email protected] [email protected]"
};
const response = await mondayApiClient.request(query, variables);
Arguments
You can use the following arguments to define which column to change and its new value.
Argument | Description |
---|---|
board_id ID! | The unique identifier of the board that contains the column to change. |
column_id String! | The column's unique identifier. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing. Requires permission to change the board structure. |
item_id ID | The unique identifier of the item to change. |
value String | The new simple value of the column. |
Change multiple column values
Required scope: boards:write
The change_multiple_column_values
mutation changes multiple column values of a specific item (row) with a JSON value via the API. You can specify which fields to return in the mutation response.
Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data in the column_values
argument, use a string and build it using this sample form: {\"text\": \"New text\", \"status\": {\"label\": \"Done\"}}
Pro tip
You can also use simple (
String
) values in this mutation along with regular (JSON
) values, or just simple values. Here's an example of setting a status with a simple value:{\"text\": \"New text\", \"status\": \"Done\"}
mutation {
change_multiple_column_values (item_id: 1234567890, board_id: 9876543210, column_values: "{\"status\": {\"index\": 1},\"date4\": {\"date\":\"2021-01-01\"}, \"person\" : {\"personsAndTeams\":[{\"id\":9603417,\"kind\":\"person\"}]}}") {
id
}
}
import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($board_id: ID!, $item_id: ID!, $column_value: JSON!) {change_multiple_column_values (item_id: $item_id, board_id: $board_id, column_values: $column_value) {id}}`;
const variables = {
board_id: 9571351437,
item_id: 9571351485,
column_id: "email_mksr9hcd",
// Each column type has a different value structure
// Check "Column types reference" section for different values
column_value: JSON.stringify({
color_mksreyj6: "In progress",
date_mksr13fh: "2025-08-27",
multiple_person_mksr4ka7: "[email protected]",
})
};
const response = await mondayApiClient.request(query, variables);
Arguments
You can use the following arguments to define which columns to change and their new values.
Argument | Definition |
---|---|
board_id ID! | The unique identifier of the board that contains the columns to change. |
column_values JSON! | The updated column values. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing. Requires permission to change the board structure. |
item_id ID | The unique identifier of the item to change. |
Change a column title
Required scope: boards:write
The change_column_title
mutation changes the title of an existing column via the API. You can specify which fields to return from the updated column in the mutation response.
mutation {
change_column_title (board_id: 1234567890, column_id: "status", title: "new_status") {
id
}
}
import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($board_id: ID!, $column_id: String!, $title: String!) {change_column_title (board_id: $board_id, column_id: $column_id, title: $title) {id}}`;
const variables = {
board_id: 9571351437,
column_id: "status",
title: "New title"
};
const response = await mondayApiClient.request(query, variables);
Arguments
You can use the following arguments to define which column's title to change and its new value.
Argument | Definition |
---|---|
board_id ID! | The unique identifier of the board that contains the column to change. |
column_id String! | The column's unique identifier. |
title String! | The column's new title. |
Update column
Required scope: boards:write
The update_column
mutation updates a column via the API. The input is validated against the column type's schema before applying changes. You can specify which fields to return from the updated column in the mutation response.
mutation{
update_column(
board_id: 1234567890,
id: "status",
title: "Work Status",
revision: "a73d19e54f82c0b7d1e348f5ac92b6de",
description: "This is my updated work status column",
column_type:status
) {
id
title
description
}
}
{
"data": {
"update_column": {
"id": "status",
"title": "Work Status",
"description": "This is my work status column"
}
},
"extensions": {
"request_id": "YOUR_REQUEST_ID"
}
}
Arguments
You can use the following arguments to define which column to update.
Argument | Description | Supported Fields |
---|---|---|
board_id ID! | The unique identifier of the board where the updated column is located. | |
capabilities ColumnCapabilitiesInput | The new column's capabilities configuration. If omitted, defaults apply: on multi-level boards, numeric, date, timeline, and status columns are created with the calculated capability enabled; in all other cases, no capabilities are applied. To override this default on multi-level boards, pass an empty argument to create the column without capabilities. Only available in API versions 2025-10 and later. | calculated CalculatedCapabilityInput |
column_type ColumnType! | The updated column's type. This determines which properties are valid in the defaults argument. | |
description String | The updated column's description. | |
id String! | The updated column's user-specified unique identifier. If not provided, a new ID will be auto-generated. If provided, it must meet the following requirements: - [1-20] characters in length (inclusive) - Only lowercase letters (a-z) and underscores (_) - Must be unique (no other column on the board can have the same ID) - Can't reuse column IDs, even if the column has been deleted from the board - Can't be null, blank, or an empty string | |
revision String! | The column's current revision. Used for optimistic concurrency control. | |
settings JSON | The column's type-specific settings in JSON. Query get_column_type_schema to see available properties. | |
title String | The updated column's title. |
Update dropdown column
Required scope: boards:write
The update_dropdown_column
mutation updates a dropdown column with strongly typed settings via the API. You can specify which fields to return from the updated dropdown column in the mutation response.
mutation {
update_dropdown_column(
board_id: 1234567890,
id: "project_category",
title: "Updated Project Category",
revision: "09606bfd3334eb88084f310fb4aef0cb",
description: "The project's updated category."
) {
description
id
title
}
}
Arguments
You can use the following arguments to define the updated dropdown column characteristics.
Argument | Description | Supported Fields |
---|---|---|
board_id ID! | The unique identifier of the board that contains the dropdown column. | |
description String | The updated dropdown column's description. | |
id String! | The unique identifier of the column to update. | |
revision String! | The column's current revision. Used for optimistic concurrency control. | |
settings UpdateDropdownColumnSettingsInput | The dropdown column's updated configuration settings. | label_limit_count Int labels [UpdateDropdownLabelInput!]! limit_select Boolean |
title String | The updated dropdown column's title. |
Update status column
Required scope: boards:write
The update_status_column
mutation updates a status column with strongly typed settings via the API. You can specify which fields to return from the updated status column in the mutation response.
mutation {
update_status_column(
board_id: 1234567890,
id: "project_status",
title: "Updated Project Status",
revision: "09606bfd3334eb88084f310fb4aef0cb",
settings: {
labels: [
{ color: peach, label: "On Hold", index: 1, is_deactivated: true},
{ color: river, label: "Done", index: 2},
{ color: grass_green, label: "Working On It", index: 3}
]
},
description: "The project's updated status."
) {
description
id
}
}
Arguments
You can use the following arguments to define the updated status column characteristics.
Argument | Description | Supported Fields |
---|---|---|
board_id ID! | The unique identifier of the board that contains the status column. | |
capabilities StatusColumnCapabilitiesInput | The status column's updated capabilities configuration. If omitted, defaults apply: on multi-level boards, numeric, date, timeline, and status columns are created with the calculated capability enabled. To override this default on multi-level boards, pass an empty argument to create the column without capabilities. | calculated StatusCalculatedCapabilityInput |
description String | The updated status column's description. | |
id String! | The unique identifier of the column to update. | |
revision String! | The column's current revision. Used for optimistic concurrency control. | |
settings UpdateStatusColumnSettingsInput | The status column's updated configuration settings. | labels [UpdateStatusLabelInput!]! |
title String | The updated status column's title. |
Change column metadata
Required scope: boards:write
The change_column_metadata
mutation updates the metadata of an existing column. Currently, we support updating both the title and description. You can specify which fields to return in the mutation response.
mutation {
change_column_metadata(board_id: 1234567890, column_id: "date4", column_property: description, value: "This is my awesome date column"){
id
title
description
}
}
import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($board_id: ID!, $column_id: String!, $desc: String!) {change_column_metadata (board_id: $board_id, column_id: $column_id, column_property: description, value: $desc) {id}}`;
const variables = {
board_id: 9571351437,
column_id: "status",
desc: "New title"
};
const response = await mondayApiClient.request(query, variables);
Arguments
You can use the following arguments to define which column to change and its new value.
Argument | Definition | Enum values |
---|---|---|
board_id ID! | The unique identifier of the board that contains the column to change. | |
column_id String! | The column's unique identifier. | |
column_property ColumnProperty | The property you want to change. | description title |
value String | The new value of that property. |
Delete a column
Required scope: boards:write
The delete_column
mutation deletes a single column from a board via the API. You can specify which fields to return from the deleted column in the mutation response.
mutation {
delete_column (board_id: 1234567890, column_id: "status") {
id
}
}
import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($board_id: ID!, $column_id: String!) { delete_column(board_id: $board_id, column_id: $column_id) { id }}`;
const variables = {
board_id: 9571351437,
column_id: "status",
};
const response = await mondayApiClient.request(query, variables);
Arguments
You can use the following arguments to define which column to delete.
Argument | Description |
---|---|
board_id ID! | The unique identifier of the board that contains the column to delete. |
column_id String! | The column's unique identifier. |