Items are core objects in the monday.com platform that hold the actual data within the board. To better illustrate the platform, imagine each board as a table, and an item is a single row in that table. Take one row, fill it with whatever information you'd like, and you now have an item!

🚧
Want to read all items on a board?
The items object allows you to query specific items by their IDs. If you want to read all items on a board, use the items_page object instead!

Queries

Get items

Required scope:boards:read
Returns an array containing metadata about one or a collection of specific items
Can only be queried directly at the root; can't be nested within another query

query {
  items(ids: [1234567890, 9876543210, 2345678901]) {
    name
  }
}

Arguments

Argument	Type	Description
exclude_nonactive	`Boolean`	Excludes items that are inactive, deleted, or belong to deleted items. Only works when used with the `ids` argument.
ids	`[ID!]`	The IDs of the specific items, subitems, or parent items to return. Maximum of 100 IDs at one time using the `limit` argument.
limit	`Int`	The number of items returned. The default is 25, and the maximum is 100.
newest_first	`Boolean`	Lists the most recently created items at the top.
page	`Int`	The page number to return. Starts at 1.

Fields

Field	Type	Description	Enum Values
assets	`[Asset]`	The item's assets/files.
board	`Board`	The board that contains the item.
column_values	`[ColumnValue]`	The item's column values.
created_at	`Date`	The item's creation date.
creator	`User`	The item's creator.
creator_id	`String!`	The unique identifier of the item's creator. Returns `null` if the item was created by default on the board.
description	`ItemDescription`	The item's description.
email	`String!`	The item's email.
group	`Group`	The item's group.
id	`ID!`	The item's unique identifier.
linked_items	`[Item!]!`	The item's linked items.
name	`String!`	The item's name.
parent_item	`Item`	A subitem's parent item. Returns `null` if querying a parent item.
relative_link	`String`	The item's relative path.
state	`State`	The item's state.	`active` `all` `archived` `deleted`
subitems	`[Item]`	The item's subitems.
subscribers	`[User]!`	The item's subscribers.
updated_at	`Date`	The date the item was last updated.
updates	`[Update!]`	The item's updates.
url	`String!`	The item's URL.

Mutations

Required scope: boards:write

Create item

Creates a new item. Returns Item.

Item data is stored in columns that hold particular information based on the column type. Each type expects a different set of parameters to update its values. When sending data to a particular column, use a JSON-formatted string. If you're using JavaScript, you can use JSON.stringify() to convert a JSON object into a string.

You can also use simple values in this mutation or combine them with regular values. Read more about sending data for each column in our column types reference.

mutation {
  create_item(
    board_id: 1234567890
    group_id: "group_one" 
    item_name: "new item" 
    column_values: "{\"date\":\"2023-05-25\"}"
	) {
    id
  }
}

Arguments

Argument	Type	Description	Accepted Values
board_id	`ID!`	The board's unique identifier.
column_values	`JSON`	The column values of the new item.
create_labels_if_missing	`Boolean`	Creates status/dropdown labels if they are missing (requires permission to change the board structure).
group_id	`String`	The group's unique identifier.
item_name	`String!`	The new item's name.
position_relative_method	`PositionRelative`	Specifies where to place the item in relation to another item. Must be used with `relative_to`.	You can use this argument in conjunction with `relative_to` to specify which item you want to create the new item above or below. `before_at`: This enum value creates the new item above the `relative_to` value. If you don't use the `relative_to` argument, the new item will be created at the bottom of the first active group (unless you specify a group using `group_id`). `after_at`: This enum value creates the new item below the `relative_to` value. If you don't use the `relative_to` argument, the new item will be created at the top of the first active group (unless you specify a group using `group_id`).
relative_to	`ID`	The unique identifier of an item on the same board to set the position relative to. Must be used with `position_relative_method`.

Duplicate item

Duplicates an item (or subitem) and its nested subitems. Returns Item.

Note: Updates shouldn't be requested in the response as they're duplicated asynchronously.

mutation {
  duplicate_item(
    board_id: 1234567890
    item_id: 9876543210 
    with_updates: true
  ) {
    id
  }
}

Arguments

Argument	Type	Description
board_id	`ID!`	The board's unique identifier.
item_id	`ID`	The item's unique identifier. Required.
with_updates	`Boolean`	Duplicates the item with existing updates.

Change an item's position

Changes an item's position on the same board. Returns Item.

mutation { 
 change_item_position(
  item_id: 1234567890
  relative_to: 9876543210
  position_relative_method: after_at
 ) {
  id
  group {
   id
  }
 }
}

Arguments

Argument	Type	Description	Enum Values
group_id	`ID`	The unique identifier of an existing group. Must be used with `group_top`.
group_top	`Boolean`	Specifies if the item will be placed at the top or bottom of the group. Must be used with `group_id`.
item_id	`ID!`	The item's unique identifier. Moving subitems or converting an item to a subitem is not currently supported.
position_relative_method	`PositionRelative`	Specifies where to place the item in relation to another item. Must be used with `relative_to`.	`after_at` (moves the item below the relative_to value) `before_at` (moves the item above the relative_to value)
relative_to	`ID`	The unique identifier of an item on the same board to set the position relative to. Must be used with `position_relative_method`.

Set item description content

🚧
Only available in versions 2026-04 and later

Updates an item's description using markdown. The provided markdown is converted into document blocks and replaces the item's existing content. Returns DocBlocksFromMarkdownResult.

mutation {
  set_item_description_content(
    item_id: 1234567890
    markdown: "**The updated description!**"
  ) {
    success
    error
    block_ids
  }
}

Arguments

Argument	Type	Description	Notes
item_id	`ID!`	The item's unique identifier.
markdown	`String!`	The item's updated description content.	Markdown doesn't support text colors or background highlights. Any existing colored or highlighted text will be lost.

Update assets on item

Updates the files in a file column. Returns Item.

mutation {
  update_assets_on_item(
    board_id: 1234567890
    item_id: 9876543210
    column_id: "YOUR_COLUMN_ID"
    files: {
      fileType: asset
      name: "New asset"
      assetId: 12345
      linkToFile: "https://yourlink.com"
    }
  ) {
    assets {
      id
      name
      url
    }
  }
}

Arguments

Argument	Type	Description
board_id	`ID!`	The board's unique identifier.
column_id	`String!`	The column's unique identifier.
files	`[FileInput!]!`	An object containing the file's input values.
item_id	`ID!`	The item's unique identifier.

Move item to group

Moves an item (or subitem) and its nested subitems between groups on the same board. Returns Item.

🚧
Multi-level board validations
The operation will be blocked if it would create a parent–child cycle (e.g., an item becoming an ancestor or descendant of itself) or if the resulting depth on the target board would exceed 5.

mutation {
  move_item_to_group(
    item_id: 1234567890, 
    group_id: "group_one"
	) {
    id
  }
}

Arguments

Argument	Type	Description
group_id	`String!`	The group's unique identifier.
item_id	`ID`	The item's unique identifier.

Move item to board

Moves an item (or subitem) and its nested subitems to a different board. Returns Item.

🚧
Multi-level board validations
The operation will be blocked if it would create a parent–child cycle (e.g., an item becoming an ancestor or descendant of itself) or if the resulting depth on the target board would exceed 5.

mutation {
  move_item_to_board(
    board_id: 1234567890
    group_id: "new_group"
    item_id: 9876543210
    columns_mapping: [
      { source: "status", target: "status2" }
      { source: "person", target: "person" }
      { source: "date", target: "date4" }
    ]
  ) {
    id
  }
}

Arguments

Argument	Type	Description
board_id	`ID!`	The unique identifier of the board to move the item to (target board)
group_id	`ID!`	The unique identifier of the group to move the item to (target group).
item_id	`ID!`	The unique identifier of the item to move.
columns_mapping	`[ColumnMappingInput!]`	The object that defines the column mapping between the original and target board. Every column type can be mapped except for formula columns. When using this argument, you must specify the mapping for all columns. You can select the target as `null` for any columns you don't want to map, but doing so will lose the column's data. If you omit this argument, the columns will be mapped based on the best match.
subitems_columns_mapping	`[ColumnMappingInput!]`	The object that defines the subitems' column mapping between the original and target board. Every column type can be mapped except for formula columns. When using this argument, you must specify the mapping for all columns. You can select the target as `null` for any columns you don't want to map, but doing so will lose the column's data. If you omit this argument, the columns will be mapped based on the best match.

Archive item

Archives an item (or subitem) and its nested subitems. Returns Item.

mutation {
  archive_item(item_id: 1234567890) {
    id
  }
}

Arguments

Argument	Type	Description
item_id	`ID!`	The item's unique identifier.

Clear item updates

Clears all updates on a specific item, including replies and likes. Returns Item.

mutation {
  clear_item_updates(
    item_id: 1234567890
	) {
    id
  }
}

Arguments

Arguments	Type	Description
item_id	`ID!`	The item's unique identifier.

Delete item

Deletes an item (or subitem) and its nested subitems. Returns Item.

mutation {
  delete_item(
    item_id: 1234567890
	) {
    id
  }
}

Arguments

Argument	Type	Description
item_id	`ID`	The item's unique identifier.