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

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

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:

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:

DEFAULT_PAGINATED_SELECT

Default fields returned by items_page:

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

External References

Edit this page

Last updated 5 hours ago

Was this page helpful?

Group

Methods

query

create

update

delete

archive

duplicate

move_item

items_page

Response Structure

Typical Response Pattern

Constants

DEFAULT_SELECT

DEFAULT_PAGINATED_SELECT

Error Handling

External References