Group

Access and manage groups via the client.group resource.

What are Groups?

Groups are sections within boards that organize related items together. Think of them like folders or categories that help structure your board's content. Each board can have multiple groups, and items can be moved between groups.

Methods

query

Retrieves groups from boards.

client.group.query(args: {}, select: DEFAULT_SELECT)

Parameters:

Name	Type	Default	Description
args	Hash	{}	Query arguments (board IDs, filters)
select	Array	["id", "title"]	Fields to retrieve

Returns: Monday::Response

Common args:

• ids - Array of board IDs to query groups from

Example:

response = client.group.query(
  args: { ids: [123, 456] },
  select: ["id", "title", "color", "position"]
)

boards = response.body.dig("data", "boards")
boards.each do |board|
  board["groups"].each do |group|
    puts "#{group['title']} (#{group['id']})"
  end
end

GraphQL: query { boards { groups { ... } } }

See: monday.com groups query

create

Creates a new group on a board.

client.group.create(args: {}, select: DEFAULT_SELECT)

Parameters:

Name	Type	Default	Description
args	Hash	{}	Creation arguments (required)
select	Array	["id", "title"]	Fields to retrieve

Required args:

• board_id - String or Integer - Board ID
• group_name - String - Name for the new group

Optional args:

• position - String - Position relative to other groups (:first, :last, or after a specific group ID)
• position_relative_method - Symbol - :before_at or :after_at when using position with group ID
• relative_to - String - Group ID to position relative to

Returns: Monday::Response

Example:

response = client.group.create(
  args: {
    board_id: 123,
    group_name: "Returned Orders"
  }
)

group = response.body.dig("data", "create_group")
puts "Created group: #{group['title']} (#{group['id']})"

GraphQL: mutation { create_group { ... } }

See: monday.com create_group

update

Updates a group's attributes.

client.group.update(args: {}, select: ["id"])

Parameters:

Name	Type	Default	Description
args	Hash	{}	Update arguments (required)
select	Array	["id"]	Fields to retrieve

Required args:

• board_id - String or Integer - Board ID
• group_id - String - Group ID
• group_attribute - Symbol - Attribute to update (:title, :color, :position)
• new_value - String - New value for the attribute

Returns: Monday::Response

Example:

response = client.group.update(
  args: {
    board_id: 123,
    group_id: "group_mkx1yn2n",
    group_attribute: :title,
    new_value: "Completed Orders"
  }
)

group = response.body.dig("data", "update_group")

GraphQL: mutation { update_group { ... } }

See: monday.com update_group

delete

Permanently deletes a group.

client.group.delete(args: {}, select: ["id"])

Parameters:

Name	Type	Default	Description
args	Hash	{}	Deletion arguments (required)
select	Array	["id"]	Fields to retrieve

Required args:

• board_id - String or Integer - Board ID
• group_id - String - Group ID to delete

Returns: Monday::Response

Permanent Deletion

Deleting a group permanently removes all items within it. This operation cannot be undone. Consider archiving instead to preserve data.

Example:

response = client.group.delete(
  args: {
    board_id: 123,
    group_id: "group_mkx1yn2n"
  }
)

deleted_group = response.body.dig("data", "delete_group")

GraphQL: mutation { delete_group { ... } }

See: monday.com delete_group

archive

Archives a group (soft delete).

client.group.archive(args: {}, select: ["id"])

Parameters:

Name	Type	Default	Description
args	Hash	{}	Archive arguments (required)
select	Array	["id"]	Fields to retrieve

Required args:

• board_id - String or Integer - Board ID
• group_id - String - Group ID to archive

Returns: Monday::Response

Example:

response = client.group.archive(
  args: {
    board_id: 123,
    group_id: "group_mkx1yn2n"
  }
)

archived_group = response.body.dig("data", "archive_group")

GraphQL: mutation { archive_group { ... } }

See: monday.com archive_group

duplicate

Duplicates an existing group.

client.group.duplicate(args: {}, select: DEFAULT_SELECT)

Parameters:

Name	Type	Default	Description
args	Hash	{}	Duplication arguments (required)
select	Array	["id", "title"]	Fields to retrieve

Required args:

• board_id - String or Integer - Board ID
• group_id - String - Group ID to duplicate

Optional args:

• add_to_top - Boolean - Add duplicated group to top of board (default: false)
• group_title - String - Custom title for duplicated group

Returns: Monday::Response

Example:

response = client.group.duplicate(
  args: {
    board_id: 123,
    group_id: "group_mkx1yn2n",
    group_title: "Copy of Returned Orders",
    add_to_top: true
  }
)

duplicated_group = response.body.dig("data", "duplicate_group")
puts "Duplicated: #{duplicated_group['title']}"

GraphQL: mutation { duplicate_group { ... } }

See: monday.com duplicate_group

move_item

Moves an item to a different group.

client.group.move_item(args: {}, select: ["id"])

Parameters:

Name	Type	Default	Description
args	Hash	{}	Move arguments (required)
select	Array	["id"]	Item fields to retrieve

Required args:

• item_id - String or Integer - Item ID to move
• group_id - String - Destination group ID

Returns: Monday::Response

Example:

response = client.group.move_item(
  args: {
    item_id: 987654321,
    group_id: "group_mkx1yn2n"
  },
  select: ["id", "name", "group { id title }"]
)

moved_item = response.body.dig("data", "move_item_to_group")

GraphQL: mutation { move_item_to_group { ... } }

See: monday.com move_item_to_group

items_page

Retrieves paginated items from groups using cursor-based pagination.

client.group.items_page(
  board_ids:,
  group_ids:,
  limit: 25,
  cursor: nil,
  query_params: nil,
  select: DEFAULT_PAGINATED_SELECT
)

Parameters:

Name	Type	Default	Description
board_ids	Integer or Array	-	Board ID(s) to query (required)
group_ids	String or Array	-	Group ID(s) to query (required)
limit	Integer	25	Items per page (max: 500)
cursor	String	nil	Pagination cursor from previous response
query_params	Hash	nil	Filter items with rules and operators
select	Array	["id", "name"]	Item fields to retrieve

Returns: Monday::Response

The response contains items and cursor for pagination:

items_page = response.body.dig("data", "boards", 0, "groups", 0, "items_page")
items = items_page["items"]
cursor = items_page["cursor"]  # Use for next page, nil if no more pages

Pagination:

Cursors are temporary tokens that expire after 60 minutes. They mark your position in the result set and enable efficient pagination through large datasets.

Query Params Structure:

{
  rules: [
    {
      column_id: "status",
      compare_value: [1, 2],  # Array of acceptable values
      operator: :any_of       # Optional: :any_of, :not_any_of, etc.
    }
  ],
  operator: :and  # Combines multiple rules: :and or :or
}

Example - Basic Pagination:

# First page
response = client.group.items_page(
  board_ids: 123,
  group_ids: "group_mkx1yn2n",
  limit: 50
)

items_page = response.body.dig("data", "boards", 0, "groups", 0, "items_page")
items = items_page["items"]
cursor = items_page["cursor"]

# Next page
if cursor
  response = client.group.items_page(
    board_ids: 123,
    group_ids: "group_mkx1yn2n",
    cursor: cursor
  )
end

Example - Multiple Boards and Groups:

response = client.group.items_page(
  board_ids: [123, 456],
  group_ids: ["group_1", "group_2"],
  limit: 100
)

boards = response.body.dig("data", "boards")
boards.each do |board|
  board["groups"].each do |group|
    items = group["items_page"]["items"]
    puts "Group #{group['items_page']['items'].length} items"
  end
end

Example - Filtered Query:

response = client.group.items_page(
  board_ids: 123,
  group_ids: "group_mkx1yn2n",
  limit: 100,
  query_params: {
    rules: [
      { column_id: "status", compare_value: [1] }
    ],
    operator: :and
  }
)

# Only items matching the filter are returned
items = response.body.dig("data", "boards", 0, "groups", 0, "items_page", "items")

Example - Custom Fields:

response = client.group.items_page(
  board_ids: 123,
  group_ids: "group_mkx1yn2n",
  limit: 50,
  select: [
    "id",
    "name",
    "created_at",
    "updated_at",
    {
      column_values: ["id", "text", "value"]
    }
  ]
)

GraphQL: query { boards { groups { items_page { ... } } } }

See:

• monday.com items_page
• Pagination guide
• Query params filtering

Response Structure

All methods return a Monday::Response object. Access data using:

response.success?  # => true/false
response.status    # => 200
response.body      # => Hash with GraphQL response

Typical Response Pattern

response = client.group.query(args: { ids: [123] })

if response.success?
  boards = response.body.dig("data", "boards")
  boards.each do |board|
    board["groups"].each do |group|
      puts group["title"]
    end
  end
else
  # Handle error
end

Constants

DEFAULT_SELECT

Default fields returned by query, create, duplicate:

["id", "title"]

DEFAULT_PAGINATED_SELECT

Default fields returned by items_page:

["id", "name"]

Error Handling

See the Error Handling guide for common errors and how to handle them.

Common errors:

• Monday::ResourceNotFoundError - Group or board not found
• Monday::AuthorizationError - Invalid permissions or token
• Monday::InvalidRequestError - Invalid arguments

Related Resources

• Item - Items within groups
• Board - Boards containing groups
• Column - Columns in groups

External References

• monday.com Groups API
• monday.com items_page
• GraphQL API Overview