Services

Attention

The services documented below are automatically initialized as part of MondayClient and should be accessed through the MondayClient instance.

Note

The fields parameters in this class’s methods directly correspond to monday.com’s API GraphQL fields. For example, using fields='id name owners { id }' or fields=Fields('id name owners { id }') is equivalent to requesting id name owners { id } in a GraphQL query.

See also

Complete documentation of available premade fields in the Fields Reference.

Boards

async Boards.query(board_ids=None, board_kind='all', order_by='created', items_page_limit=25, boards_limit=25, page=1, state='active', workspace_ids=None, fields=Fields('id name'), *, group_ids=None, paginate_items=True, paginate_boards=True)[source]

Query boards to return metadata about one or multiple boards.

Parameters:

  • board_ids (int | str | list[int | str] | None) – The ID or list of IDs of the boards to query.

  • paginate_items (bool) – Whether to paginate items if items_page is in fields.

  • paginate_boards (bool) – Whether to paginate boards. If False, only returns the first page.

  • board_kind (Literal['private', 'public', 'share', 'all']) – The kind of boards to include.

  • order_by (Literal['created', 'used']) – The order in which to return the boards.

  • items_page_limit (int) – The number of items to return per page when items_page is part of your fields.

  • boards_limit (int) – The number of boards to return per page.

  • page (int) – The page number to start from.

  • state (Literal['active', 'all', 'archived', 'deleted']) – The state of the boards to include.

  • workspace_ids (int | str | list[int | str] | None) – The ID or list of IDs of the workspaces to filter by.

  • group_ids (str | list[str] | None) – The ID or list of IDs of groups to filter returned data by.

  • fields (str | Fields) – Fields to return from the queried board. Can be a string of space-separated field names or a Fields() instance.

Return type:

list[Board]

Returns:

List of Board dataclass instances containing queried board data.

Raises:

Example

>>> from monday import MondayClient, Config
>>> config = Config(api_key='your_api_key')
>>> monday_client = MondayClient(config)
>>> boards = await monday_client.boards.query(
...     board_ids=987654321,
...     fields='id name state'
... )
>>> boards[0].id
"987654321"
>>> boards[0].name
"Board 1"
>>> boards[0].state
"active"
async Boards.get_items(board_ids, query_params=None, limit=25, group_id=None, fields=Fields('id name'), *, paginate_items=True, group_ids=None)[source]

Retrieves a paginated list of items from specified boards.

Note

This method supports filtering using QueryParams. For examples and detailed information about building complex queries, see Query Types in the Types documentation.

Parameters:

  • board_ids (int | str | list[int | str]) – The ID or list of IDs of the boards from which to retrieve items.

  • query_params (QueryParams | dict[str, Any] | None) – A set of parameters to filter, sort, and control the scope of the underlying boards query. Use this to customize the results based on specific criteria. Can be a QueryParams object or a dictionary.

  • limit (int) – The maximum number of items to retrieve per page.

  • group_id (str | None) – Only retrieve items from the specified group ID. If both group_id and group_ids are provided, group_ids takes precedence.

  • group_ids (str | list[str] | None) – The group ID or list of group IDs to restrict the items to. When provided, items are fetched under each matching group using a groups selection with ids.

  • paginate_items (bool) – Whether to paginate items. If False, only returns the first page.

  • fields (str | Fields) – Fields to return from the items. Can be a string of space-separated field names or a Fields() instance.

Return type:

list[ItemList]

Returns:

A list of ItemList dataclass instances containing the board IDs and their combined items retrieved.

Raises:

Example

>>> from monday import MondayClient, QueryParams, QueryRule
>>> monday_client = MondayClient(api_key='your_api_key')

# Using QueryParams objects (recommended for type safety)
>>> query_params = QueryParams(
...     rules=[
...         QueryRule(
...             column_id='status',
...             compare_value=['Done'],
...             operator='contains_terms'
...         )
...     ]
... )
>>> item_lists = await monday_client.boards.get_items(
...     board_ids=987654321,
...     query_params=query_params,
...     limit=50
... )

# Using dictionary format (equivalent functionality)
>>> item_lists = await monday_client.boards.get_items(
...     board_ids=987654321,
...     query_params={
...         'rules': [
...             {
...                 'column_id': 'status',
...                 'compare_value': ['Done'],
...                 'operator': 'contains_terms'
...             }
...         ]
...     },
...     limit=50
... )
>>> item_lists[0].board_id
"987654321"
>>> len(item_lists[0].items)
25
>>> item_lists[0].items[0].name
"Task 1"
async Boards.get_items_by_column_values(board_id, columns, limit=25, *, paginate_items=True, fields=Fields('id name'))[source]

Retrieves items from a board based on specific column values.

Parameters:

  • board_id (int | str) – The ID of the board from which to retrieve items.

  • columns (list[ColumnFilter]) – A list of ColumnFilter objects specifying the column values to filter by.

  • limit (int) – The maximum number of items to retrieve per page.

  • paginate_items (bool) – Whether to paginate items. If False, only returns the first page.

  • fields (str | Fields) – Fields to return from the items. Can be a string of space-separated field names or a Fields() instance.

Return type:

list[Item]

Returns:

A list of Item dataclass instances containing the filtered items.

Raises:

Example

>>> from monday import MondayClient, ColumnFilter
>>> monday_client = MondayClient(api_key='your_api_key')

# Using ColumnFilter objects (recommended for type safety)
>>> columns = [
...     ColumnFilter(
...         column_id='status',
...         column_values=['Done', 'In Progress']
...     ),
...     ColumnFilter(
...         column_id='priority',
...         column_values=['High']
...     )
... ]
>>> items = await monday_client.boards.get_items_by_column_values(
...     board_id=987654321,
...     columns=columns,
...     limit=50
... )

# Using dictionary format (equivalent functionality)
>>> columns = [
...     {'column_id': 'status', 'column_values': ['Done', 'In Progress']},
...     {'column_id': 'priority', 'column_values': ['High']}
... ]
>>> items = await monday_client.boards.get_items_by_column_values(
...     board_id=987654321,
...     columns=[ColumnFilter(**col) for col in columns],
...     limit=50
... )
>>> len(items)
25
async Boards.get_column_values(board_id, column_ids, column_fields=Fields('id text value column { title }'), item_fields=Fields('id name'))[source]

Retrieves column values for specific columns on a board.

Parameters:

  • board_id (int | str) – The ID of the board from which to retrieve column values.

  • column_ids (str | list[str]) – The ID or list of IDs of the columns to retrieve values for.

  • column_fields (str | Fields) – Fields to return from the columns. Can be a string of space-separated field names or a Fields() instance.

  • item_fields (str | Fields) – Fields to return from the items. Can be a string of space-separated field names or a Fields() instance.

Return type:

list[Item]

Returns:

A list of Item dataclass instances containing the column values.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> items = await monday_client.boards.get_column_values(
...     board_id=987654321,
...     column_ids=['status', 'priority'],
...     column_fields='id title type',
...     item_fields='id name'
... )
>>> len(items)
25
async Boards.create(name, board_kind='public', owner_ids=None, owner_team_ids=None, subscriber_ids=None, subscriber_teams_ids=None, description=None, folder_id=None, template_id=None, workspace_id=None, fields=Fields('id name'))[source]

Creates a new board on monday.com.

Parameters:

  • name (str) – The name of the board to create.

  • board_kind (Optional[Literal['private', 'public', 'share']]) – The kind of board to create.

  • owner_ids (list[int | str] | None) – List of user IDs to set as board owners.

  • owner_team_ids (list[int | str] | None) – List of team IDs to set as board owner teams.

  • subscriber_ids (list[int | str] | None) – List of user IDs to subscribe to the board.

  • subscriber_teams_ids (list[int | str] | None) – List of team IDs to subscribe to the board.

  • description (str | None) – A description for the board.

  • folder_id (int | str | None) – The ID of the folder to place the board in.

  • template_id (int | str | None) – The ID of the template to use for the board.

  • workspace_id (int | str | None) – The ID of the workspace to place the board in.

  • fields (str | Fields) – Fields to return from the created board. Can be a string of space-separated field names or a Fields() instance.

Return type:

Board

Returns:

A Board dataclass instance containing the created board data.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> board = await monday_client.boards.create(
...     name='New Project Board',
...     board_kind='public',
...     description='A board for tracking project progress'
... )
>>> board.id
"987654321"
>>> board.name
"New Project Board"
async Boards.duplicate(board_id, board_name=None, duplicate_type='with_structure', folder_id=None, workspace_id=None, fields=Fields('id name'), *, keep_subscribers=False)[source]

Duplicates an existing board on monday.com.

Parameters:

  • board_id (int | str) – The ID of the board to duplicate.

  • board_name (str | None) – The name for the duplicated board. If None, will use the original name with “Copy” appended.

  • duplicate_type (Literal['with_pulses', 'with_pulses_and_updates', 'with_structure']) – The type of duplication to perform.

  • folder_id (int | str | None) – The ID of the folder to place the duplicated board in.

  • workspace_id (int | str | None) – The ID of the workspace to place the duplicated board in.

  • fields (str | Fields) – Fields to return from the duplicated board. Can be a string of space-separated field names or a Fields() instance.

  • keep_subscribers (bool) – Whether to keep the original board’s subscribers on the duplicated board.

Return type:

Board

Returns:

A Board dataclass instance containing the duplicated board data.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> duplicated_board = await monday_client.boards.duplicate(
...     board_id=987654321,
...     board_name='Project Board Copy',
...     duplicate_type='with_structure'
... )
>>> duplicated_board.id
"987654322"
>>> duplicated_board.name
"Project Board Copy"
async Boards.update(board_id, board_attribute, new_value)[source]

Updates a specific attribute of a board.

Parameters:

  • board_id (int | str) – The ID of the board to update.

  • board_attribute (Literal['communication', 'description', 'name']) – The attribute of the board to update.

  • new_value (str) – The new value for the specified attribute.

Return type:

UpdateBoard

Returns:

An UpdateBoard dataclass instance containing the update result.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> result = await monday_client.boards.update(
...     board_id=987654321,
...     board_attribute='name',
...     new_value='Updated Board Name'
... )
>>> result.success
True
>>> result.name
"Updated Board Name"
async Boards.archive(board_id, fields=Fields('id name'))[source]

Archives a board on monday.com.

Parameters:

  • board_id (int | str) – The ID of the board to archive.

  • fields (str | Fields) – Fields to return from the archived board. Can be a string of space-separated field names or a Fields() instance.

Return type:

Board

Returns:

A Board dataclass instance containing the archived board data.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> archived_board = await monday_client.boards.archive(
...     board_id=987654321
... )
>>> archived_board.state
"archived"
async Boards.delete(board_id, fields=Fields('id name'))[source]

Deletes a board from monday.com.

Parameters:

  • board_id (int | str) – The ID of the board to delete.

  • fields (str | Fields) – Fields to return from the deleted board. Can be a string of space-separated field names or a Fields() instance.

Return type:

Board

Returns:

A Board dataclass instance containing the deleted board data.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> deleted_board = await monday_client.boards.delete(
...     board_id=987654321
... )
>>> deleted_board.state
"deleted"
async Boards.create_column(board_id, column_type, title, defaults=None, after_column_id=None, fields=Fields('id text value column { title }'))[source]

Creates a new column on a board.

Parameters:

  • board_id (int | str) – The ID of the board to add the column to.

  • column_type (Literal['auto_number', 'board_relation', 'button', 'checkbox', 'color_picker', 'country', 'creation_log', 'date', 'dependency', 'doc', 'subtasks', 'dropdown', 'email', 'file', 'formula', 'hour', 'item_assignees', 'item_id', 'last_updated', 'link', 'location', 'long_text', 'mirror', 'name', 'numbers', 'people', 'phone', 'progress', 'rating', 'status', 'tags', 'team', 'text', 'timeline', 'time_tracking', 'vote', 'week', 'world_clock', 'unsupported']) – The type of column to create.

  • title (str) – The title of the new column.

  • defaults (dict[str, Any] | StatusDefaults | DropdownDefaults | None) – Default values for the column. Can be a dictionary or ColumnDefaults object. The format depends on the column type.

  • after_column_id (str | None) – The ID of the column to place the new column after.

  • fields (str | Fields) – Fields to return from the created column. Can be a string of space-separated field names or a Fields() instance.

Return type:

Column

Returns:

A Column dataclass instance containing the created column data.

Raises:

Example

>>> from monday import MondayClient
>>> from monday.types.column_defaults import StatusDefaults, StatusLabel, DropdownDefaults, DropdownLabel
>>> monday_client = MondayClient(api_key='your_api_key')

# Using StatusDefaults objects (recommended for type safety)
>>> column = await monday_client.boards.create_column(
...     board_id=987654321,
...     column_type='status',
...     title='Priority',
...     defaults=StatusDefaults(
...         labels=[
...             StatusLabel('Low', 0),
...             StatusLabel('Medium', 1),
...             StatusLabel('High', 2)
...         ]
...     )
... )

# Using dictionary format (equivalent functionality)
>>> column = await monday_client.boards.create_column(
...     board_id=987654321,
...     column_type='status',
...     title='Priority',
...     defaults={
...         'labels': {
...             0: 'Low',
...             1: 'Medium',
...             2: 'High'
...         }
...     }
... )
>>> column.id
"status_123"
>>> column.title
"Priority"

# Creating a dropdown column with custom options
>>> dropdown_column = await monday_client.boards.create_column(
...     board_id=987654321,
...     column_type='dropdown',
...     title='Category',
...     defaults=DropdownDefaults(
...         options=[
...             DropdownLabel('Bug'),
...             DropdownLabel('Feature'),
...             DropdownLabel('Enhancement'),
...             DropdownLabel('Documentation')
...         ]
...     )
... )

# Using dictionary format for dropdown (equivalent functionality)
>>> dropdown_column = await monday_client.boards.create_column(
...     board_id=987654321,
...     column_type='dropdown',
...     title='Category',
...     defaults={
...         'settings': {
...             'labels': [
...                 {'id': 0, 'name': 'Bug'},
...                 {'id': 1, 'name': 'Feature'},
...                 {'id': 2, 'name': 'Enhancement'},
...                 {'id': 3, 'name': 'Documentation'}
...             ]
...         }
...     }
... )

Groups

async Groups.query(board_ids, group_ids=None, group_name=None, fields=Fields('id title'))[source]

Query groups from boards. Optionally specify the group names and/or IDs to filter by.

Parameters:

  • board_ids (int | str | list[int | str]) – The ID or list of IDs of the boards to query.

  • group_ids (str | list[str] | None) – The ID or list of IDs of the specific groups to return.

  • group_name (str | list[str] | None) – A single group name or list of group names.

  • fields (str | Fields) – Fields to return from the queried groups.

Return type:

list[GroupList]

Returns:

List of GroupList dataclass instances containing board IDs and their associated Group dataclass instances.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> result = await monday_client.groups.query(
...     board_ids=987654321,
...     fields='id title'
... )
>>> result[0].board_id
"987654321"
>>> result[0].groups[0].id
"group"
>>> result[0].groups[0].title
"Group Name"
async Groups.create(board_id, group_name, group_color=None, relative_to=None, position_relative_method=None, fields=Fields('id title'))[source]

Create a new group on a board.

Parameters:

  • board_id (int | str) – The ID of the board where the group will be created.

  • group_name (str) – The new group’s name.

  • group_color (str | None) – The new group’s HEX code color.

  • relative_to (str | None) – The ID of the group you want to create the new one in relation to.

  • position_relative_method (Optional[Literal['before', 'after']]) – Specify whether you want to create the new group above or below the group given to relative_to. Accepts 'before' or 'after' (internally mapped to API enums before_at/after_at).

  • fields (str | Fields) – Fields to return from the created group.

Return type:

Group

Returns:

Group dataclass instance containing info for the new group.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> group = await monday_client.groups.create(
...     board_id=987654321,
...     group_name='Group Name',
...     group_color='#0086c0',
...     fields='id title'
... )
>>> group.id
"group"
>>> group.title
"Group Name"
>>> group.color
"#0086c0"

Note

See a full list of accepted HEX code values for group_color and their corresponding colors here.

async Groups.update(board_id, group_id, attribute, new_value, fields=Fields('id title'))[source]

Update a group.

Parameters:

  • board_id (int | str) – The ID of the board where the group will be updated.

  • group_id (str) – The ID of the group to update.

  • attribute (Literal['color', 'position', 'relative_position_after', 'relative_position_before', 'title']) – The group attribute to update. When 'color', provide a supported hex code (e.g., #0086c0). When using position-related attributes (relative_position_after or relative_position_before), new_value should be the ID of the reference group. When 'title', new_value is the new title string.

  • new_value (str) – The new value for the specified attribute. For 'color', pass a supported hex code (e.g., #0086c0); for position attributes (relative_position_after/relative_position_before), pass the reference group ID; for 'title', pass the new title string.

  • fields (str | Fields) – Fields to return from the updated group.

Return type:

Group

Returns:

Group dataclass instance containing info for the updated group.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> group = await monday_client.groups.update(
...     board_id=987654321,
...     group_id='group',
...     attribute='color',
...     new_value='#7f5347',
...     fields='id title color'
... )
>>> group.id
"group"
>>> group.title
"Group Name"
>>> group.color
"#7F5347"

Note

When using attribute='color', see a full list of accepted HEX color codes and their corresponding colors here.

When updating a group’s position using relative_position_after or relative_position_before, the new_value should be the ID of the group you intend to place the updated group above or below.

async Groups.duplicate(board_id, group_id, group_title=None, fields=Fields('id title'), *, add_to_top=False)[source]

Duplicate a group.

Parameters:

  • board_id (int | str) – The ID of the board where the group will be duplicated.

  • group_id (str) – The ID of the group to duplicate.

  • add_to_top (bool) – Whether to add the new group to the top of the board.

  • group_title (str | None) – The new group’s title.

  • fields (str | Fields) – Fields to return from the duplicated group.

Return type:

Group

Returns:

Group dataclass instance containing info for the duplicated group.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> group = await monday_client.groups.duplicate(
...     board_id=987654321,
...     group_id='group',
...     fields='id title'
... )
>>> group.id
"group_2"
>>> group.title
"Duplicate of Group Name"
async Groups.archive(board_id, group_id, fields=Fields('id title'))[source]

Archive a group.

Parameters:

  • board_id (int | str) – The ID of the board where the group will be archived.

  • group_id (str) – The ID of the group to archive.

  • fields (str | Fields) – Fields to return from the archived group.

Return type:

Group

Returns:

Group dataclass instance containing info for the archived group.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> group = await monday_client.groups.archive(
...     board_id=987654321,
...     group_id='group',
...     fields='id title archived'
... )
>>> group.id
"group"
>>> group.title
"Group Name"
>>> group.archived
True
async Groups.delete(board_id, group_id, fields=Fields('id title'))[source]

Delete a group.

Parameters:

  • board_id (int | str) – The ID of the board where the group will be deleted.

  • group_id (str) – The ID of the group to delete.

  • fields (str | Fields) – Fields to return from the deleted group.

Return type:

Group

Returns:

Group dataclass instance containing info for the deleted group.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> group = await monday_client.groups.delete(
...     board_id=987654321,
...     group_id='group',
...     fields='id title deleted'
... )
>>> group.id
"group"
>>> group.title
"Group Name"
>>> group.deleted
True
async Groups.get_items_by_name(board_id, group_id, item_name, item_fields=Fields('id name'))[source]

Get all items from a group with names that match item_name

Parameters:

  • board_id (int | str) – The ID of the board to query.

  • group_id (str) – A single group ID.

  • item_name (str) – The name of the item to match.

  • item_fields (str | Fields) – Fields to return from the matched items.

Return type:

list[Item]

Returns:

List of Item dataclass instances containing item info.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> items = await monday_client.groups.get_items_by_name(
...     board_id=987654321,
...     group_id='group',
...     item_name='Item Name',
...     item_fields='id name'
... )
>>> items[0].id
"123456789"
>>> items[0].name
"Item Name"
>>> items[1].id
"012345678"
>>> items[1].name
"Item Name"

Note

Groups.create(position_relative_method) accepts 'before' or 'after' which map internally to the API enums before_at/after_at.

Items

async Items.query(item_ids, limit=25, page=1, fields=Fields('id name'), *, exclude_nonactive=False, newest_first=False)[source]

Query items to return metadata about one or multiple items.

Parameters:

  • item_ids (int | str | list[int | str]) – The ID or list of IDs of the specific items to return. Maximum of 100 IDs allowed in a single query.

  • limit (int) – The maximum number of items to retrieve per page. Must be greater than 0 and less than 100.

  • page (int) – The page number at which to start.

  • exclude_nonactive (bool) – Excludes items that are inactive, deleted, or belong to deleted items.

  • newest_first (bool) – Lists the most recently created items at the top.

  • fields (str | Fields) – Fields to return from the queried items.

Return type:

list[Item]

Returns:

A list of Item dataclass instances containing info for the queried items.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> items = await monday_client.items.query(
...     item_ids=[123456789, 123456780],
...     fields='id name state updates { text_body }',
...     limit=50
... )
>>> items[0].id
"123456789"
>>> items[0].name
"Task 1"
>>> items[0].state
"active"
>>> items[0].updates[0].text_body
"Started working on this"

Note

To return all items on a board, use Boards.get_items() instead.

async Items.create(board_id, item_name, column_values=None, group_id=None, position_relative_method=None, relative_to=None, fields=Fields('id name'), *, create_labels_if_missing=False)[source]

Create a new item on a board.

Parameters:
Return type:

Item

Returns:

Item dataclass instance containing info for the created item.

Raises:

Example

>>> from monday import MondayClient
>>> from monday.types.column_inputs import StatusInput, TextInput, DateInput
>>> monday_client = MondayClient(api_key='your_api_key')

# Using ColumnInput objects (recommended for type safety)
>>> item = await monday_client.items.create(
...     board_id=987654321,
...     item_name='New Item',
...     column_values=[
...         StatusInput('status_column_id', 'Done'),
...         TextInput('text_column_id', 'This item is done'),
...         DateInput('date_column_id', '2024-01-15')
...     ],
...     group_id='group',
...     fields='id name column_values (ids: ["status_column_id", "text_column_id"]) { id text }'
... )

# Using dictionary format (equivalent functionality)
>>> item = await monday_client.items.create(
...     board_id=987654321,
...     item_name='New Item',
...     column_values={
...         'status_column_id': {'label': 'Done'},
...         'text_column_id': 'This item is done',
...         'date_column_id': {'date': '2024-01-15'}
...     },
...     group_id='group',
...     fields='id name column_values (ids: ["status_column_id", "text_column_id"]) { id text }'
... )
>>> item.id
"987654321"
>>> item.name
"New Item"
>>> item.column_values[0].id
"status_column_id"
>>> item.column_values[0].text
"Done"
async Items.duplicate(item_id, board_id, new_item_name=None, fields=Fields('id name'), *, with_updates=False)[source]

Duplicate an item.

Parameters:

  • item_id (int | str) – The ID of the item to be duplicated.

  • board_id (int | str) – The ID of the board where the item will be duplicated.

  • with_updates (bool) – Duplicates the item with existing updates.

  • new_item_name (str | None) – Name of the duplicated item. If omitted the duplicated item’s name will be the original item’s name with (copy) appended.

  • fields (str | Fields) – Fields to return from the duplicated item.

Return type:

Item

Returns:

Item dataclass instance containing info for the duplicated item.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> item = await monday_client.items.duplicate(
...     item_id=123456789,
...     board_id=987654321,
...     fields='id name column_values { id text }'
... )
>>> item.id
"123456789"
>>> item.name
"Item 1 (copy)"
>>> item.column_values[0].id
"status"
>>> item.column_values[0].text
"Done"
async Items.move_to_group(item_id, group_id, fields=Fields('id name'))[source]

Move an item to a different group.

Parameters:

  • item_id (int | str) – The ID of the item to be moved.

  • group_id (str) – The ID of the group to move the item to.

  • fields (str | Fields) – Fields to return from the moved item.

Return type:

Item

Returns:

Item dataclass instance containing info for the moved item.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> item = await monday_client.items.move_to_group(
...     item_id=123456789,
...     group_id='group',
...     fields='id name group { id title }'
... )
>>> item.id
"123456789"
>>> item.name
"Item 1"
>>> item.group.id
"group"
>>> item.group.title
"Group 1"
async Items.move_to_board(item_id, board_id, group_id, columns_mapping=None, subitems_columns_mapping=None, fields=Fields('id name'))[source]

Move an item to a different board.

Parameters:

  • item_id (int | str) – The ID of the item to be moved.

  • board_id (int | str) – The ID of the board to move the item to.

  • group_id (str) – The ID of the group to move the item to.

  • columns_mapping (list[dict[str, str]] | dict[str, str] | None) – Defines the column mapping between the original and target board.

  • subitems_columns_mapping (list[dict[str, str]] | dict[str, str] | None) – Defines the subitems’ column mapping between the original and target board.

  • fields (str | Fields) – Fields to return from the moved item.

Return type:

Item

Returns:

Item dataclass instance containing info for the moved item.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> item = await monday_client.items.move_to_board(
...     item_id=123456789,
...     board_id=987654321,
...     group_id='group',
...     columns_mapping={
...         'original_status_id': 'target_status_id',
...         'original_text_id': 'target_text_id'
...     },
...     fields='id board { id } group { id } column_values { id text }'
... )
>>> item.id
"123456789"
>>> item.board.id
"987654321"
>>> item.group.id
"group"
>>> item.column_values[0].id
"target_status_id"
>>> item.column_values[0].text
"Done"

Note

Every column type can be mapped except for formula columns.

When using the columns_mapping and subitem_columns_mapping arguments, you must specify the mapping for all columns. You can set the target as None for any columns you don’t want to map, but doing so will lose the column’s data.

If you omit this argument, the columns will be mapped based on the best match.

See the monday.com API documentation (move item) for more details.

async Items.archive(item_id, fields=Fields('id name'))[source]

Archive an item.

Parameters:

  • item_id (int | str) – The ID of the item to be archived.

  • fields (str | Fields) – Fields to return from the archived item.

Return type:

Item

Returns:

Item dataclass instance containing info for the archived item.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> item = await monday_client.items.archive(
...     item_id=123456789,
...     fields='id state'
... )
>>> item.id
"123456789"
>>> item.state
"archived"
async Items.delete(item_id, fields=Fields('id name'))[source]

Delete an item.

Parameters:

  • item_id (int | str) – The ID of the item to be deleted.

  • fields (str | Fields) – Fields to return from the deleted item.

Return type:

Item

Returns:

Item dataclass instance containing info for the deleted item.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> item = await monday_client.items.delete(
...     item_id=123456789,
...     fields='id state'
... )
>>> item.id
"123456789"
>>> item.state
"deleted"
async Items.clear_updates(item_id, fields=Fields('id name'))[source]

Clear an item’s updates.

Parameters:

  • item_id (int | str) – The ID of the item to be cleared.

  • fields (str | Fields) – Fields to return from the cleared item.

Return type:

Item

Returns:

Item dataclass instance containing info for the cleared item.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> item = await monday_client.items.clear_updates(
...     item_id=123456789,
...     fields='id updates { text_body }'
... )
>>> item.id
"123456789"
>>> item.updates
[]
async Items.get_column_values(item_id, column_ids=None, fields=Fields('id text value column { title }'))[source]

Retrieves a list of column values for a specific item.

Parameters:

  • item_id (int | str) – The ID of the item.

  • column_ids (list[str] | None) – The specific column IDs to return. Will return all columns if no IDs specified.

  • fields (str | Fields) – Fields to return from the item column values.

Return type:

list[ColumnValue]

Returns:

A list of ColumnValue dataclass instances containing the item column values.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> column_values = await monday_client.items.get_column_values(
...     item_id=123456789,
...     column_ids=['status', 'text'],
...     fields='id text'
... )
>>> column_values[0].id
"status"
>>> column_values[0].text
"Done"
>>> column_values[1].id
"text"
>>> column_values[1].text
"This item is done"

Note

Use Boards.get_column_values() to retrieve column values for all items on a board.

async Items.change_column_values(item_id, column_values, fields=Fields('id text value column { title }'), *, create_labels_if_missing=False)[source]

Change an item’s column values.

Parameters:
Return type:

ColumnValue

Returns:

ColumnValue dataclass instance for the updated columns payload returned by the API.

Raises:

Example

>>> from monday import MondayClient
>>> from monday.types.column_inputs import DateInput, StatusInput, TextInput
>>> monday_client = MondayClient(api_key='your_api_key')

# Using ColumnInput objects (recommended for type safety)
>>> col_val = await monday_client.items.change_column_values(
...     item_id=123456789,
...     column_values=[
...         StatusInput('status_column_id', 'Working on it'),
...         TextInput('text_column_id', 'Working on this item'),
...         DateInput('date_column_id', '2024-01-15', '14:30:00')
...     ],
...     fields='id column_values { id text }'
... )

# Using dictionary format (equivalent functionality)
>>> col_val = await monday_client.items.change_column_values(
...     item_id=123456789,
...     column_values={
...         'status_column_id': {'label': 'Working on it'},
...         'text_column_id': 'Working on this item',
...         'date_column_id': {'date': '2024-01-15', 'time': '14:30:00'},
...         'status_2_column_id': {'label': 'Done'}  # Supports dict format
...     },
...     fields='id column_values { id text }'
... )
>>> col_val.id
"123456789"

Note

Each column has a certain type, and different column types expect a different set of parameters to update their values.

For better type safety and documentation, you can use the value classes from Column Input Types:

These classes handle the proper formatting required by the Monday.com API and provide validation.

See the monday.com API documentation (column types reference) for more details on which parameters to use for each column type.

async Items.get_name(item_id)[source]

Get an item name from an item ID.

Parameters:

item_id (int | str) – The ID of the item.

Return type:

str

Returns:

The item name.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> await monday_client.items.get_name(item_id=123456789)
"Item 1"
async Items.get_id(board_id, item_name)[source]

Get the IDs of all items on a board with names matching the given item name.

Parameters:

  • board_id (int | str) – The ID of the board to search.

  • item_name (str) – The item name to filter on.

Return type:

list[str]

Returns:

List of item IDs matching the item name.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> await monday_client.items.get_id(
...     board_id=987654321,
...     item_name='Item 1'
... )
[
    "123456789",
    "012345678"
]

Note

Items.create(position_relative_method) accepts 'before_at' or 'after_at' to align with the underlying API enums.

Subitems

async Subitems.query(item_ids, subitem_ids=None, fields=Fields('id name'), **kwargs)[source]

Query items to return metadata about one or multiple subitems.

Parameters:

  • item_ids (int | str | list[int | str]) – The ID or list of IDs of the specific items containing the subitems to return.

  • subitem_ids (int | str | list[int | str] | None) – The ID or list of IDs of the specific subitems to return.

  • fields (str | Fields) – Fields to return from the queried subitems.

  • **kwargs (Any) – Additional keyword arguments for the underlying Items.query() call.

Return type:

list[SubitemList]

Returns:

A list of SubitemList dataclass instances containing item IDs and their associated subitems.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> result = await monday_client.subitems.query(
...     item_ids=[123456789, 012345678],
...     subitem_ids=[987654321, 098765432, 998765432],
...     fields='id name state updates { text_body }'
... )
>>> result[0].item_id
"123456789"
>>> result[0].subitems[0].id
"987654321"
>>> result[0].subitems[0].name
"subitem"
>>> result[0].subitems[0].state
"active"
async Subitems.create(item_id, subitem_name, column_values=None, fields=Fields('id name'), *, create_labels_if_missing=False)[source]

Create a new subitem on an item.

Parameters:
Return type:

Subitem

Returns:

Subitem dataclass instance containing info for the created subitem.

Raises:

Example

>>> from monday import MondayClient
>>> from monday.types.column_inputs import StatusInput, TextInput
>>> monday_client = MondayClient(api_key='your_api_key')

# Using ColumnInput objects (recommended for type safety)
>>> subitem = await monday_client.subitems.create(
...     item_id=123456789,
...     subitem_name='New Subitem',
...     column_values={
...         'status': StatusInput('status', 'Done'),
...         'text': TextInput('text', 'This subitem is done')
...     },
...     fields='id name column_values (ids: ["status", "text"]) { id text }'
... )

# Using dictionary format (equivalent functionality)
>>> subitem = await monday_client.subitems.create(
...     item_id=123456789,
...     subitem_name='New Subitem',
...     column_values={
...         'status': {'label': 'Done'},
...         'text': 'This subitem is done'
...     },
...     fields='id name column_values (ids: ["status", "text"]) { id text }'
... )
>>> subitem.id
"123456789"
>>> subitem.name
"New Subitem"
>>> subitem.column_values[0].id
"status"
>>> subitem.column_values[0].text
"Done"

Users

async Users.query(emails=None, ids=None, name=None, kind='all', limit=50, page=1, fields=Fields('id email'), *, paginate=True, newest_first=False, non_active=False)[source]

Query users to return metadata about one or multiple users.

Parameters:

  • emails (str | list[str] | None) – The specific user emails to return.

  • ids (int | str | list[int | str] | None) – The IDs of the specific users to return.

  • name (str | None) – A fuzzy search of users by name.

  • kind (Literal['all', 'guests', 'non_guests', 'non_pending']) – The kind of users to search by.

  • newest_first (bool) – Lists the most recently created users at the top.

  • non_active (bool) – Returns non-active users.

  • limit (int) – The number of users to get per page.

  • page (int) – The page number to start from.

  • paginate (bool) – Whether to paginate results or just return the first page.

  • fields (str | Fields) – Fields to return from the queried users.

Return type:

list[User]

Returns:

List of User dataclass instances containing info for the queried users.

Raises:

Example

>>> from monday import MondayClient
>>> monday_client = MondayClient(api_key='your_api_key')
>>> users = await monday_client.users.query(
...     emails=[
...         'user1@domain.com',
...         'user2@domain.com'
...     ],
...     fields='id name'
... )
>>> users[0].id
"12345678"
>>> users[0].name
"User One"
>>> users[1].id
"01234567"
>>> users[1].name
"User Two"

Webhooks

async Webhooks.query(board_id, *, app_webhooks_only=None, fields=Fields('id event board_id config'))[source]

Query webhooks configured for a specific board.

Parameters:

  • board_id (int | str) – The unique identifier of the board to query webhooks for.

  • app_webhooks_only (bool | None) – Returns only webhooks created by the app initiating the request.

  • fields (str | Fields) – Fields to return from the webhook objects.

Return type:

list[Webhook]

Returns:

A list of Webhook instances.

async Webhooks.create(board_id, url, event, *, config=None, fields=Fields('id event board_id config'))[source]

Create a webhook subscription on a board.

Parameters:

  • board_id (int | str) – The board’s unique identifier.

  • url (str) – The webhook target URL. Max length 255 characters.

  • event (Union[Literal['change_column_value', 'change_status_column_value', 'change_subitem_column_value', 'change_specific_column_value', 'change_name', 'create_item', 'item_archived', 'item_deleted', 'item_moved_to_any_group', 'item_moved_to_specific_group', 'item_restored', 'create_subitem', 'change_subitem_name', 'move_subitem', 'subitem_archived', 'subitem_deleted', 'create_column', 'create_update', 'edit_update', 'delete_update', 'create_subitem_update'], str]) – The event to listen to (WebhookEventType).

  • config (dict[str, Any] | None) – Optional configuration JSON for supported events.

  • fields (str | Fields) – Fields to return from the created webhook.

Return type:

Webhook

Returns:

A Webhook instance for the created webhook.

async Webhooks.delete(webhook_id, *, fields=Fields('id event board_id config'))[source]

Delete a webhook subscription by its ID.

Parameters:

  • webhook_id (int | str) – The webhook’s unique identifier.

  • fields (str | Fields) – Fields to return from the deleted webhook.

Return type:

Webhook

Returns:

A Webhook instance for the deleted webhook.

Related Service Guides