Items are housed together in units called groups. Each board contains one or multiple groups, and each can hold one or many items.

As a developer working with monday.com, it is important to familiarize yourself with the groups API so you know how to access and update group data. This document will walk you through the available queries and mutations to read and modify the groups object via the API.

Queries

Required scope: boards:read

Querying groups will return metadata about one or a collection of groups on a specific board. This method accepts one argument and returns an array.

You can only query groups by nesting it within another query, so it can't be used at the root.

query {
  boards (ids: 1234567890) {
    groups {
      title
      id
    }
  }
}

let query = "query { boards (ids: 1234567890) { groups { title id }}}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following arguments to reduce the number of results returned in your groups query.

Argument	Description
ids `[String]`	The specific groups to return.

Fields

You can use the following field(s) to specify what information your groups query will return. Please note that some fields will have their own arguments.

Field	Description	Supported arguments
archived `Boolean`	Returns `true` if the group is archived.
color `String!`	The group's color.
deleted `Boolean`	Returns `true` if the group is deleted.
id `ID!`	The group's unique identifier.
items_page `ItemsResponse!`	The group's items.	cursor `String` limit `Int!` query_params `ItemsQuery`
position `String!`	The group's position on the board.
title `String!`	The group's title.

Mutations

Required scope: boards:write

Create a group

The create_group mutation allows you to create a new empty group via the API. You can also specify what fields to query back from the new group when you run the mutation.

mutation {
  create_group (board_id: 1234567890, group_name: "new group", relative_to: "test_group", group_color: "#ff642e", position_relative_method: before_at) {
    id
  }
}

let query = "mutation { create_group (board_id: 1234567890, group_name: \"new group\", relative_to: \"test group\", position_relative_method: before_at) { id } }";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to define the new group's characteristics.

Argument	Description	Accepted values
board_id `ID!`	The board's unique identifier.
group_color `String`	The group's HEX code color. Please note that this argument is only available in API versions `2024-04` and later.	You can see a list of accepted HEX code values and their corresponding colors here (don't forget to include # in your string!)
group_name `String!`	The new group's name.
position `String` (DEPRECATED)	The group's position on the board.	The group's position is determined using a string containing only a number value (no letters or special characters). The higher the value, the lower the group sits on the board; the lower the value, the higher the group sits on the board. If you provide an invalid input using letters or special characters, the group will go to the top of the board. You will get an error if you provide a `number` rather than a `string`. For example: Assume Group 1 has a position of 10000 and Group 3 has a position of 30000. If you want to create a new group between the other two called Group 2, it needs a position greater than 10000 and less than 30000.
relative_to `String`	The unique identifier of the group you want to create the new one in relation to. The default creates the new group below the specified `group_id`. You can also use this argument in conjunction with `position_relative_group` to specify if you want to create the new group above or below the group in question.
position_relative_method `PositionRelative`	The desired position of the new group.	You can use this argument in conjunction with `relative_to` to specify which group you want to create the new group above or below. - `before_at`: This enum value creates the new group above the `relative_to` value. If you don't use the `relative_to` argument, the new group will be created at the bottom of the board. - `after_at`: This enum value creates the new group below the `relative_to` value. If you don't use the `relative_to` argument, the new group will be created at the top of the board.

Update a group

The update_group mutation allows you to update an existing group via the API. You can also specify what fields to query back from the updated group when you run the mutation.

mutation {
  update_group (board_id: 1234567890, group_id: "test group id", group_attribute: relative_position_before, new_value: "test_group") { 
    id
  } 
}

let query = 'mutation { update_group(board_id: 1234567890, group_id: "test group id", group_attribute: relative_position_before, new_value: "test_group")}';

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     'query' : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to specify which group to update and its new value.

Argument	Description	Accepted values
board_id `ID!`	The board's unique identifier.
group_attribute `GroupAttributes!`	The group attribute that you want to update.	The accepted attributes are title, color, position (DEPRECATED), relative_position_after, and relative_position_before.
group_id `String!`	The group's unique identifier.
new_value `String!`	The new attribute value.	You can find the list of accepted color values here. When updating a group's position using the `relative_position_after` or `relative_position_before` attributes, the new attribute value should be the unique identifier of the group you intend to place the updated group above or below.

Duplicate group

The duplicate_group mutation allows you to duplicate a group with all of its items via the API. You can also specify what fields to query back from the duplicated group when you run the mutation.

🚧
Mutation-specific rate limit
The duplicate_group mutation has an additional rate limit of 40 mutations per minute. If you exceed this limit, you will receive a response with a 429 status code, and the following error message: "Call limit exceeded for DuplicateGroup".

mutation {
  duplicate_group (board_id: 1234567890, group_id: "test group id", add_to_top: true) {
    id
  }
}

let query = "mutation { duplicate_group (board_id: 1234567890, group_id: \"test group id\", add_to_top: true) { id } }";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to specify which group to duplicate and its new properties.

Argument	Description
add_to_top `Boolean`	Boolean to add the new group to the top of the board.
board_id `ID!`	The board's unique identifier.
group_id `String!`	The group's unique identifier.
group_title `String`	The group's title.

Move item to group

The move_item_to_group mutation allows you to move an item between groups on the same board via the API. You can also specify what fields to query back when you run the mutation.

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

let query = "mutation { move_item_to_group (item_id: 1234567890, group_id: \"test group id\") { id }}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to specify which item to move and to which group.

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

Archive a group

The archive_group mutation allows you to archive a group with all of its items via the API. You can also specify what fields to query back from the archived group when you run the mutation.

mutation {
  archive_group (board_id: 1234567890, group_id: "test group id") {
    id
    archived
  }
}

let query = "mutation { archive_group (board_id: 1234567890, group_id: \"test group id\") { id archived } }";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to specify which group to archive.

Argument	Description
board_id `ID!`	The board's unique identifier.
group_id `String!`	The group's unique identifier.

Delete a group

The delete_group mutation allows you to delete a group with all of its items via the API. You can also specify what fields to query back from the deleted group when you run the mutation.

mutation {
  delete_group (board_id: 1234567890, group_id: "test group id") {
    id
    deleted
  }
}

let query = "mutation { delete_group (board_id: 1234567890, group_id: \"test group id\") { id deleted } }";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to specify which group to delete.

Argument	Description
board_id `ID!`	The board's unique identifier.
group_id `String!`	The group's unique identifier.

📘
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! 😎

Groups

Queries

Arguments

Fields

Mutations

Create a group

Arguments

Update a group

Arguments

Duplicate group

🚧
Mutation-specific rate limit

Arguments

Move item to group

Arguments

Archive a group

Arguments

Delete a group

Arguments

📘
Join our developer community!

Queries

Arguments

Fields

Mutations

Create a group

Arguments

Update a group

Arguments

Duplicate group

🚧Mutation-specific rate limit

Arguments

Move item to group

Arguments

Archive a group

Arguments

Delete a group

Arguments

📘Join our developer community!

🚧
Mutation-specific rate limit

📘
Join our developer community!