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. Check out this query in action in our Postman library or follow along with these code samples!

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.

ArgumentDescription
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.

FieldDescriptionSupported arguments
archived Boolean Returns 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 [Item]The items in the group.ids [Int]
limit Int
page Int
newest_first Boolean
exclude_nonactive Boolean
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.

Check out this mutation in action in our Postman library or follow along with these code samples!

mutation {
    create_group (board_id: 1234567890, group_name: "new group", relative_to: "test_group", 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.

ArgumentDescriptionAccepted values
board_id Int!The board's unique identifier.
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 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_group 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 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.

ArgumentDescriptionAccepted values
board_id Int!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.

ArgumentDescription
add_to_top BooleanBoolean to add the new group to the top of the board.
board_id Int!The board's unique identifier.
group_id String!The group's unique identifier.
group_title StringThe group's title.

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.

ArgumentDescription
board_id Int!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.

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

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.

ArgumentDescription
group_id String!The group's unique identifier.
item_id IntThe item'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! 😎