Apps Framework DocsCommunityAPI Playground

Groups

Suggest Edits

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

Groups queries

Required scope: boards:read

Groups are available for querying through parent items. They must be nested within another query, like a board or an item. You cannot use them at the root of your query.

Querying groups will return either one or a collection of groups on a specific board.

query {
    boards (ids: 123456789) {
        groups {
            title
            color
            position
        }
    }
}

let query = "query { boards (ids: 157244624) { groups (ids: status){ title color position }}}";

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

You can find the Postman request to get the IDs of groups on a board here.

Fields

The following fields will determine the data returned from your groups query.

FieldField DescriptionSupported arguments
archived Boolean Whether the group is archived or not.
color String!The group's color.
deleted BooleanWhether the group is deleted or not.
id ID!The group's unique identifier.
items [Item]The items in the group.Ids [Int]
limit Int
page Int
newest_first Boolean
position String!The group's position on the board.
title String!The group's title.

Groups mutations

Required scope: boards:write

Create a group

The create_group mutation creates a new empty group. After the mutation runs, you can query back all the group data as shown in the section above.

mutation {
    create_group (board_id: 123456789, group_name: "new group", position:"10000") {
        id
    }
}

let query = "mutation { create_group (board_id: 123456789, group_name: \"new group\", position: \"10000\") { id } }";

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

You can find the Postman request to create a group here.

Arguments for create a group

The following arguments define the new group's characteristics.

ArgumentDescriptionAccepted values
board_id Int!The board's identifier.
group_name String!The name of the new group.
position StringThe 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.

Update group

The update_group mutation updates an existing group. 

mutation {
  update_group (board_id: 123456789, group_id: "today", group_attribute: position, new_value: "10000") { 
    id
  } 
}

let query = 'mutation { update_group(board_id: 123456789, group_id: "today", group_attribute: position, new_value: "10000")}';

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 for update group

The following arguments define which group to update and the characteristics of the updated group.

ArgumentDescriptionAccepted values
board_id Int!The board's unique identifier.
group_id String!The group's unique identifier.
group_attribute GroupAttributes!The group attribute that you want to update. The available attributes are title, position, or color.
new_value String!The new attribute value.You can find the list of accepted color values here.

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, Group 2 has a position of 20000, and Group 3 has a position of 30000. If you want to move Group 3 to the top of the board, it needs a position of less than 10000.

Duplicate group

The duplicate_group mutation duplicates a group with all of its items. After the mutation runs you can query back all the group data as shown in the querying groups section above.

mutation {
    duplicate_group (board_id: 12345678, group_id: "today", add_to_top: true) {
        id
    }
}

let query = "mutation { duplicate_group (board_id: 20178755, group_id: \"today\", add_to_top: true) { id } }";

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

Arguments for duplicate group

The following arguments define the duplication type and the duplicated group's characteristics.

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

🚧

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

Archive a group

The archive_group mutation archives a group with all of its items. After the mutation runs, you can query back all the group data as shown in the querying groups section above.

mutation {
    archive_group (board_id: 12345678, group_id: "today") {
        id
        archived
    }
}

let query = "mutation { archive_group (board_id: 20178755, group_id: \"today\") { id archived } }";

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

Arguments for archive a group

The following archive_group arguments determine which group will be archived.

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

Delete a group

The delete_group mutation deletes a group with all of its items. After the mutation runs you can query back all the group data as shown in the querying groups section above.

mutation {
    delete_group (board_id: 12345678, group_id: "today") {
        id
        deleted
    }
}

let query = "mutation { delete_group (board_id: 20178755, group_id: \"today\") { id deleted } }";

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

Arguments for delete a group

The following arguments determine which group will be deleted.

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

Move item to group

The mutation allows you to move an item between groups in the same board. 

mutation {
    move_item_to_group (item_id: 1234567, group_id: "today") {
        id
    }
}

let query = "mutation { move_item_to_group (item_id: 1234567, group_id: \"today\") { 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 for move item to group

The following arguments determine which item is moved to which group.

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

📘

Have questions?

Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.

Don’t forget to search before opening a new topic!

Updated 4 days ago