Groups

Learn how to read, create, update, and delete groups from monday boards using the platform API

Items are organized in different sections on a board called groups. Each board contains at least one group that houses one or more items.

Queries

You can use the groups query to retrieve group data via the API.

  • Required scope: boards:read
  • Returns an array containing metadata about one or a collection of groups on a specific board
  • Can only be nested within another query (e.g., boards)
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 argument to reduce the number of results returned in your groups query.

ArgumentDescription
ids [String]The specific groups to return.

Fields

You can use the following fields to specify what information your groups query will return.

FieldDescription
archived BooleanReturns true if the group is archived.
color String!The group's color.
deleted BooleanReturns true if the group is deleted.
id ID!The group's unique identifier.
items_page ItemsResponse!The group's items.
position String!The group's position on the board.
title String!The group's title.

Mutations

The API allows you to create, update, and delete groups using the following mutations. These operations let you programmatically control a group's full lifecycle.

Create group

Required scope: boards:write

The create_group mutation creates a new empty group via the API. You can specify which fields to return in the mutation response.

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 arguments to define the new group's characteristics.

ArgumentDescriptionAccepted Values
board_id ID!The board's unique identifier.
group_color StringThe group's HEX code color. See a full 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. Maximum of 255 characters.
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 StringThe 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_method to specify if you want to create the new group above or below the group in question.
position_relative_method PositionRelativeThe 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 group

Required scope: boards:write

The update_group mutation updates an existing group via the API. You can specify which fields to return in the mutation response.

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 arguments to specify which group to update and its new value.

ArgumentDescriptionAccepted Values
board_id ID!The board's unique identifier.
group_attribute GroupAttributes!The group attribute to update. color
position
relative_position_after
relative_position_before
title
group_id String!The group's unique identifier.
new_value String!The new attribute value.See a full 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

Required scope: boards:write

The duplicate_group mutation duplicates a group and all of its items via the API. You can specify which fields to return in the mutation response.

🚧

This mutation has an additional rate limit of 40 mutations per minute.

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 arguments to specify which group to duplicate and its new properties.

ArgumentDescription
add_to_top BooleanBoolean 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 StringThe group's title.

Move item to group

The move_item_to_group mutation moves an item between groups on the same board via the API. You can specify which fields to return in the mutation response.

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 arguments to specify which item to move and to which group.

ArgumentDescription
group_id String!The group's unique identifier.
item_id IDThe item's unique identifier.

Archive group

Required scope: boards:write

The archive_group mutation archives a group and all of its items via the API. You can specify which fields to return in the mutation response.

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 arguments to specify which group to archive.

ArgumentDescription
board_id ID!The board's unique identifier.
group_id String!The group's unique identifier.

Delete group

Required scope: boards:write

The delete_group mutation deletes a group and all of its items via the API. You can specify which fields to return in the mutation response.

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 arguments to specify which group to delete.

ArgumentDescription
board_id ID!The board's unique identifier.
group_id String!The group's unique identifier.