Types

The types in this package are implemented as Python dataclasses that model the structure of Monday.com’s GraphQL API responses and query parameters.

Data Types

These dataclasses represent the structure of data returned from the Monday.com API.

For example:

@dataclass
class Item:
   name: str = ''
   updated_at: str = ''
   state: str = ''
   subitems: list[Subitem] | None = None

You can access the attributes directly:

# Get item data from API
items = await monday_client.items.query(item_ids=[123456789])

for item in items:
   print(f"Item: {item.name}")
   print(f"Last updated: {item.updated_at}")
   print(f"State: {item.state}")

   if item.subitems:
      print(f"Has {len(item.subitems)} subitems")
      for subitem in item.subitems:
         print(f"  - {subitem.name}")

Account Types

class Account(active_members_count=0, country_code='', first_day_of_the_week=None, id='', logo='', name='', plan=None, products=None, show_timeline_weekends=None, sign_up_product_kind='', slug='', tier='')[source]

Bases: object

Represents a Monday.com account with its settings and plan information.

This dataclass maps to the Monday.com API account object structure, containing fields like name, plan, products, and account settings.

See also

https://developer.monday.com/api-reference/reference/account#fields

Parameters:

  • active_members_count (int)

  • country_code (str)

  • first_day_of_the_week (Literal['monday', 'sunday'] | None)

  • id (str)

  • logo (str)

  • name (str)

  • plan (Plan | None)

  • products (AccountProduct | None)

  • show_timeline_weekends (bool | None)

  • sign_up_product_kind (str)

  • slug (str)

  • tier (str)

active_members_count: int = 0

The number of active users in the account - includes active users across all products who are not guests or viewers

country_code: str = ''

The account’s two-letter country code in ISO3166 format. The result is based on the location of the first account admin

first_day_of_the_week: Optional[Literal['monday', 'sunday']] = None

The first day of the week for the account

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Account

Parameters:

data (dict[str, Any])

id: str = ''

The account’s unique identifier

The account’s logo

name: str = ''

The account’s name

plan: Plan | None = None

The account’s payment plan. Returns None for accounts with the multi-product infrastructure

products: AccountProduct | None = None

The account’s active products

show_timeline_weekends: bool | None = None

Returns True if weekends appear in the timeline

sign_up_product_kind: str = ''

The product the account first signed up to

slug: str = ''

The account’s slug

tier: str = ''

The account’s tier. For accounts with multiple products, this will return the highest tier across all products

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class AccountProduct(id='', default_workspace_id='', kind=None)[source]

Bases: object

Represents a Monday.com account product with its configuration.

This dataclass maps to the Monday.com API account product object structure, containing fields like kind, default workspace, and unique identifier.

See also

https://developer.monday.com/api-reference/reference/other-types#account-product

Parameters:

  • id (str)

  • default_workspace_id (str)

  • kind (Literal['core', 'crm', 'forms', 'marketing', 'projectManagement', 'project_management', 'service', 'software', 'whiteboard'] | None)

default_workspace_id: str = ''

The account product’s default workspace ID

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

AccountProduct

Parameters:

data (dict[str, Any])

id: str = ''

The unique identifier of the account product

kind: Optional[Literal['core', 'crm', 'forms', 'marketing', 'projectManagement', 'project_management', 'service', 'software', 'whiteboard']] = None

The account product

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class Plan(max_users=0, period='', tier='', version=0)[source]

Bases: object

Represents a Monday.com account plan with its limits and features.

This dataclass maps to the Monday.com API plan object structure, containing fields like max users, period, tier, and version.

See also

https://developer.monday.com/api-reference/reference/plan#fields

Parameters:
classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Plan

Parameters:

data (dict[str, Any])

max_users: int = 0

The maximum number of users allowed on the plan. This will be 0 for free and developer accounts

period: str = ''

The plan’s time period

tier: str = ''

The plan’s tier

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

version: int = 0

The plan’s version

Asset Types

class Asset(created_at='', file_extension='', file_size=0, id='', name='', original_geometry='', public_url='', uploaded_by=None, url='', url_thumbnail='')[source]

Bases: object

Represents a Monday.com asset (file) with its metadata and URLs.

This dataclass maps to the Monday.com API asset object structure, containing fields like name, file size, URLs, and upload information.

See also

https://developer.monday.com/api-reference/reference/assets#fields

Parameters:

  • created_at (str)

  • file_extension (str)

  • file_size (int)

  • id (str)

  • name (str)

  • original_geometry (str)

  • public_url (str)

  • uploaded_by (User | None)

  • url (str)

  • url_thumbnail (str)

created_at: str = ''

The asset’s creation date. Returned as YYYY-MM-DDTHH:MM:SS

file_extension: str = ''

The asset’s extension

file_size: int = 0

The asset’s size in bytes

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Asset

Parameters:

data (dict[str, Any])

id: str = ''

The asset’s unique identifier

name: str = ''

The asset’s name

original_geometry: str = ''

The asset’s original geometry

public_url: str = ''

The asset’s public URL (valid for 1 hour). Accessing this link will allow users without a monday.com user profile to see the file directly while the link is valid.

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

uploaded_by: User | None = None

The user who uploaded the asset. This field will not return anything if the asset is a duplicate of something generated by a system.

url: str = ''

The asset’s URL. This will only be available to users who have access to the file as part of your account. If the asset is stored on a private or shareable board, it will also need to be part of the board in question.

url_thumbnail: str = ''

The URL to view the asset in thumbnail mode. Only available for images.

Board Types

class Board(activity_logs=None, board_folder_id='', board_kind='', columns=None, communication='', created_at='', creator=None, creator_id='', description='', groups=None, id='', items=None, items_count=0, name='', owners=None, permissions='', pos='', state='', subscribers=None, tags=None, top_group=None, type='', updated_at='', workspace=None, workspace_id='')[source]

Bases: object

Represents a Monday.com board with all its properties and relationships.

This dataclass maps to the Monday.com API board object structure, containing fields like name, description, columns, groups, and associated users.

See also

https://developer.monday.com/api-reference/reference/boards#fields

Parameters:
activity_logs: list[dict[str, Any]] | None = None

The board’s activity logs

board_folder_id: str = ''

The board’s folder unique identifier

board_kind: str = ''

The board’s kind

columns: list[Column] | None = None

The board’s columns

communication: str = ''

The board’s communication

created_at: str = ''

The board’s creation date. Returned as YYYY-MM-DDTHH:MM:SS

creator: User | None = None

The board’s creator

creator_id: str = ''

The board’s creator unique identifier

description: str = ''

The board’s description

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Board

Parameters:

data (dict[str, Any])

groups: list[Group] | None = None

The board’s groups

id: str = ''

The board’s unique identifier

items: list[Item] | None = None

The board’s items

items_count: int = 0

The number of items on the board

name: str = ''

The board’s name

owners: list[User] | None = None

The board’s owners

permissions: str = ''

The board’s permissions

pos: str = ''

The board’s position

state: str = ''

The board’s state

subscribers: list[User] | None = None

The board’s subscribers

tags: list[dict[str, Any]] | None = None

The board’s tags

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

top_group: Group | None = None

The board’s top group

type: str = ''

The board’s type

updated_at: str = ''

The board’s last update date. Returned as YYYY-MM-DDTHH:MM:SS

workspace: Workspace | None = None

The board’s workspace

workspace_id: str = ''

The board’s workspace unique identifier

class ActivityLog(account_id='', data='', entity=None, event='', id='', user_id='', created_at='')[source]

Bases: object

Type definitions for monday.com API activity log structures.

These types correspond to Monday.com’s activity log view fields as documented in their API reference: https://developer.monday.com/api-reference/reference/activity-logs#fields

Parameters:
account_id: str = ''

The unique identifier of the account that initiated the event

created_at: str = ''

The time of the event in 17-digit unix time

data: str = ''

The item’s column values

entity: Optional[Literal['board', 'pulse']] = None

The entity of the event that was changed

event: str = ''

The action that took place

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

ActivityLog

Parameters:

data (dict[str, Any])

id: str = ''

The unique identifier of the activity log event

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

user_id: str = ''

The unique identifier of the user who initiated the event

class BoardView(id='', name='', settings_str='', type='', view_specific_data_str='')[source]

Bases: object

Type definitions for monday.com API board view structures.

These types correspond to Monday.com’s board view fields as documented in their API reference: https://developer.monday.com/api-reference/reference/board-views#fields

Parameters:

  • id (str)

  • name (str)

  • settings_str (str)

  • type (str)

  • view_specific_data_str (str)

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

BoardView

Parameters:

data (dict[str, Any])

id: str = ''

The view’s unique identifier

name: str = ''

The view’s name

settings_str: str = ''

The view’s settings

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

type: str = ''

The view’s type

view_specific_data_str: str = ''

Specific board view data (only supported for forms)

class UndoData(undo_record_id='', action_type='', entity_type='', entity_id='', count=0)[source]

Bases: object

Structure containing undo information for board operations.

Example

undo_data = {
    'undo_record_id': 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    'action_type': 'modify_project',
    'entity_type': 'Board',
    'entity_id': 987654321,
    'count': 1,
}
Parameters:

  • undo_record_id (str)

  • action_type (str)

  • entity_type (str)

  • entity_id (str)

  • count (int)

action_type: str = ''

Type of action performed (e.g., ‘modify_project’)

count: int = 0

Number of entities affected by the operation

entity_id: str = ''

ID of the entity that was modified

entity_type: str = ''

Type of entity modified (e.g., ‘Board’)

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

UndoData

Parameters:

data (dict[str, Any])

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

undo_record_id: str = ''

Unique identifier for the undo record

class UpdateBoard(id='', name='', updated_attribute='', previous_attribute=None, success=False, undo_data=None)[source]

Bases: object

Response structure for board update operations.

Example

response = {
    'success': True,
    'undo_data': {
        'undo_record_id': 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
        'action_type': 'modify_project',
        'entity_type': 'Board',
        'entity_id': 987654321,
        'count': 1,
    },
}
Parameters:

  • id (str)

  • name (str)

  • updated_attribute (str)

  • previous_attribute (str | None)

  • success (bool)

  • undo_data (UndoData | None)

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

UpdateBoard

Parameters:

data (dict[str, Any])

id: str = ''

The id of the updated board

name: str = ''

The name of the updated board

previous_attribute: str | None = None

The value of the attribute before it was updated

success: bool = False

Whether the update operation was successful

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

undo_data: UndoData | None = None

Information needed to undo the update operation

updated_attribute: str = ''

The value of the updated attribute

Column Types

class Column(archived=False, description='', id='', settings_str='', title='', type='', width=0)[source]

Bases: object

Represents a Monday.com column with its properties and settings.

This dataclass maps to the Monday.com API column object structure, containing fields like title, type, settings, and metadata.

See also

https://developer.monday.com/api-reference/reference/columns#fields

Parameters:
archived: bool = False

Returns True if the column is archived

description: str = ''

The column’s description

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Column

Parameters:

data (dict[str, Any])

id: str = ''

The column’s unique identifier

settings_str: str = ''

The column’s settings as a JSON string

title: str = ''

The column’s title

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

type: str = ''

The column’s type

width: int = 0

The column’s width

class ColumnValue(additional_info='', id='', text='', title='', type='', value=<factory>, column=None, display_value='', label='', color='')[source]

Bases: object

Represents a Monday.com column value with its data and metadata.

This dataclass maps to the Monday.com API column value object structure, containing fields like text, value, type, and associated column metadata.

See also

https://developer.monday.com/api-reference/reference/column-values#fields

Parameters:
additional_info: str = ''

The column value’s additional info

color: str = ''

Color value for fragment queries like … on ButtonValue

column: Column | None = None

The column metadata associated with this value

display_value: str = ''

Display value for fragment queries like … on MirrorValue, … on BoardRelationValue

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

ColumnValue

Parameters:

data (dict[str, Any])

id: str = ''

The column value’s unique identifier

label: str = ''

Label value for fragment queries like … on ButtonValue

text: str = ''

The column value’s text

title: str = ''

The column value’s title

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

type: str = ''

The column value’s type

value: dict

The column value’s value

class ColumnFilter(column_id, column_values)[source]

Bases: object

Structure for filtering items by column values.

Example

column_filter = ColumnFilter(
    column_id='status', column_values=['Done', 'In Progress']
)

# Or with a single value
column_filter = ColumnFilter(column_id='text', column_values='Search term')
Parameters:
column_id: str

The ID of the column to filter by

column_values: str | list[str]

The value(s) to filter for. Can be a single string or list of strings

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

ColumnFilter

Parameters:

data (dict[str, Any])

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

monday.types.column.ColumnType: Literal

Literal of supported column type names used throughout the API.

Group Types

class Group(archived=False, color='', deleted=False, id='', items=None, position='', title='')[source]

Bases: object

Represents a Monday.com group with its properties and items.

This dataclass maps to the Monday.com API group object structure, containing fields like title, color, position, and associated items.

See also

https://developer.monday.com/api-reference/reference/groups#fields

Parameters:
archived: bool = False

Returns True if the group is archived

color: str = ''

The group’s color

deleted: bool = False

Returns True if the group is deleted

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Group

Parameters:

data (dict[str, Any])

id: str = ''

The group’s unique identifier

items: list[Item] | None = None

The group’s items

position: str = ''

The group’s position on the board

title: str = ''

The group’s title

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class GroupList(board_id, groups)[source]

Bases: object

Type definition for a list of groups associated with a board.

This structure is used by the Groups.query() method to return groups grouped by their board ID.

Parameters:
board_id: str

The ID of the board that contains the groups

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

GroupList

Parameters:

data (dict[str, Any])

groups: list[Group]

The list of groups belonging to the board

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

Item Types

Note

Items can be filtered and queried using QueryParams and QueryRule. See Query Types for details.

class Item(assets=None, board=None, column_values=None, created_at='', creator=None, creator_id='', group=None, id='', name='', state='', subitems=None, subscribers=None, updated_at='', updates=None, email='', url='', relative_link='', linked_items=None, parent_item=None)[source]

Bases: object

Represents a Monday.com item (row) with its data and relationships.

This dataclass maps to the Monday.com API item object structure, containing fields like name, column values, updates, and associated board/group information.

See also

https://developer.monday.com/api-reference/reference/items#fields

Parameters:
assets: list[Asset] | None = None

The item’s assets/files

board: Board | None = None

The board that contains the item

column_values: list[ColumnValue] | None = None

The item’s column values

created_at: str = ''

The item’s creation date. Returned as YYYY-MM-DDTHH:MM:SS

creator: User | None = None

The item’s creator

creator_id: str = ''

The unique identifier of the item’s creator. Returns None if the item was created by default on the board.

email: str = ''

The item’s email (when available).

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Item

Parameters:

data (dict[str, Any])

group: Group | None = None

The item’s group

id: str = ''

The item’s unique identifier

linked_items: list['Item'] | None = None

The item’s linked items (when available).

name: str = ''

The item’s name

parent_item: Item' | None = None

The parent item, when this Item represents a subitem (e.g., parent_item { … }).

The item’s relative path (when available).

state: str = ''

The item’s state

subitems: list[Subitem] | None = None

The item’s subitems

subscribers: list[User] | None = None

The item’s subscribers

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

updated_at: str = ''

The date the item was last updated. Returned as YYYY-MM-DDTHH:MM:SS

updates: list[Update] | None = None

The item’s updates

url: str = ''

The item’s link URL (when available).

class ItemList(board_id, items)[source]

Bases: object

Type definition for a list of items associated with a board.

This structure is used by the Boards.get_items() method to return items grouped by their board ID.

Parameters:
board_id: str

The ID of the board that contains the items

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

ItemList

Parameters:

data (dict[str, Any])

items: list[Item]

The list of items belonging to the board

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class ItemsPage(items=None, cursor='')[source]

Bases: object

Represents a paginated page of Monday.com items with cursor for navigation.

This dataclass maps to the Monday.com API items page structure, containing a list of items and a cursor for retrieving the next page.

See also

https://developer.monday.com/api-reference/reference/items#fields

Parameters:
cursor: str = ''

cursor for retrieving the next page of items

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

ItemsPage

Parameters:

data (dict[str, Any])

items: list[Any] | None = None

List of items

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class OrderBy(column_id, direction='asc')[source]

Bases: object

Structure for ordering items in queries.

Parameters:

  • column_id (str)

  • direction (Literal['asc', 'desc'])

column_id: str

The ID of the column to order by

direction: Literal['asc', 'desc'] = 'asc'

The direction to order items. Defaults to ‘asc’ if not specified

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

OrderBy

Parameters:

data (dict[str, Any])

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class QueryRule(column_id, compare_value, operator='any_of', compare_attribute='')[source]

Bases: object

Structure for defining item query rules.

Parameters:

  • column_id (str)

  • compare_value (list[str | int])

  • operator (Literal['any_of', 'not_any_of', 'is_empty', 'is_not_empty', 'greater_than', 'greater_than_or_equals', 'lower_than', 'lower_than_or_equal', 'between', 'not_contains_text', 'contains_text', 'contains_terms', 'starts_with', 'ends_with', 'within_the_next', 'within_the_last'])

  • compare_attribute (str)

column_id: str

The ID of the column to filter on

compare_attribute: str = ''

The attribute to compare (optional)

compare_value: list[str | int]

List of values to compare against

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

QueryRule

Parameters:

data (dict[str, Any])

operator: Literal['any_of', 'not_any_of', 'is_empty', 'is_not_empty', 'greater_than', 'greater_than_or_equals', 'lower_than', 'lower_than_or_equal', 'between', 'not_contains_text', 'contains_text', 'contains_terms', 'starts_with', 'ends_with', 'within_the_next', 'within_the_last'] = 'any_of'

The comparison operator to use. Defaults to any_of if not specified

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class QueryParams(rules=<factory>, operator='and', order_by=None, ids=<factory>)[source]

Bases: object

Structure for complex item queries.

Example

query_params = QueryParams(
    rules=[
        QueryRule(
            column_id='status',
            compare_value=['Done', 'In Progress'],
            operator='any_of',
        )
    ],
    operator='and',
    order_by=OrderBy(column_id='date', direction='desc'),
)

Note

For examples of how to use QueryParams to filter items, see Filtering and Querying Items in the Usage documentation.

Parameters:
classmethod from_dict(data)[source]

Create from dictionary.

Return type:

QueryParams

Parameters:

data (dict[str, Any])

ids: list[int]

The specific item IDs to return. The maximum is 100.

operator: Literal['and', 'or'] = 'and'

How to combine multiple rules. Defaults to ‘and’ if not specified

order_by: OrderBy | None = None

Optional ordering configuration

rules: list[QueryRule]

List of query rules to apply

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

Subitem Types

class Subitem(assets=None, board=None, created_at='', column_values=None, creator=None, creator_id='', email='', group=None, id='', item_id='', linked_items=None, parent_item=None, relative_link='', name='', state='', updated_at='', subitems=None, subscribers=None, updates=None, url='')[source]

Bases: object

Represents a Monday.com subitem with its properties and relationships.

This dataclass maps to the Monday.com API subitem object structure, containing fields like name, state, and associated board/group information.

See also

https://developer.monday.com/api-reference/reference/subitems#fields

Parameters:

  • assets (list['Asset'] | None)

  • board (Board | None)

  • created_at (str)

  • column_values (list['ColumnValue'] | None)

  • creator ('User' | None)

  • creator_id (str)

  • email (str)

  • group (Group | None)

  • id (str)

  • item_id (str)

  • linked_items (list['Item'] | None)

  • parent_item ('Item' | None)

  • relative_link (str)

  • name (str)

  • state (str)

  • updated_at (str)

  • subitems (list['Item'] | None)

  • subscribers (list['User'] | None)

  • updates (list['Update'] | None)

  • url (str)

assets: list['Asset'] | None = None

The subitem’s assets/files

board: Board | None = None

The subitem’s board

column_values: list['ColumnValue'] | None = None

The subitem’s column values

created_at: str = ''

The subitem’s creation date. Returned as YYYY-MM-DDTHH:MM:SS

creator: User' | None = None

The subitem’s creator

creator_id: str = ''

The subitem’s creator unique identifier

email: str = ''

The subitem’s email

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Subitem

Parameters:

data (dict[str, Any])

group: Group | None = None

The subitem’s group

id: str = ''

The subitem’s unique identifier

item_id: str = ''

The subitem’s parent item unique identifier

linked_items: list['Item'] | None = None

The subitem’s linked items

name: str = ''

The subitem’s name

parent_item: Item' | None = None

The subitem’s parent item object when requested via fields (e.g., parent_item { id name })

The subitem’s relative path

state: str = ''

The subitem’s state

subitems: list['Item'] | None = None

The subitem’s subitems (nested items)

subscribers: list['User'] | None = None

The subitem’s subscribers

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

updated_at: str = ''

The subitem’s last update date. Returned as YYYY-MM-DDTHH:MM:SS

updates: list['Update'] | None = None

The subitem’s updates

url: str = ''

The subitem’s link

class SubitemList(item_id, subitems)[source]

Bases: object

Type definition for a list of subitems associated with a parent item.

This structure is used by the Subitems.query() method to return subitems grouped by their parent item ID.

Parameters:
classmethod from_dict(data)[source]

Create from dictionary.

Return type:

SubitemList

Parameters:

data (dict[str, Any])

item_id: str

The ID of the parent item that contains the subitems

subitems: list[Subitem]

The list of subitems belonging to the parent item

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

Tag Types

class Tag(color='', id='', name='')[source]

Bases: object

Represents a Monday.com tag with its color and name.

This dataclass maps to the Monday.com API tag object structure, containing fields like name, color, and unique identifier.

See also

https://developer.monday.com/api-reference/reference/tags#fields

Parameters:
color: str = ''

The tag’s color

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Tag

Parameters:

data (dict[str, Any])

id: str = ''

The tag’s unique identifier

name: str = ''

The tag’s name

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

Team Types

class Team(id='', name='', owners=None, picture_url='', users=None)[source]

Bases: object

Represents a Monday.com team with its members and owners.

This dataclass maps to the Monday.com API team object structure, containing fields like name, picture URL, owners, and team members.

See also

https://developer.monday.com/api-reference/reference/teams#fields

Parameters:
classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Team

Parameters:

data (dict[str, Any])

id: str = ''

The team’s unique identifier

name: str = ''

The team’s name

owners: list[User] | None = None

The users that are the team’s owners (see User)

picture_url: str = ''

The team’s picture URL

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

users: list[User] | None = None

The team’s users (see User)

Update Types

class Update(assets=None, body='', created_at='', creator=None, creator_id='', id='', item_id='', parent_id='', replies=None, text_body='', updated_at='')[source]

Bases: object

Represents a Monday.com update (comment) with its content and metadata.

This dataclass maps to the Monday.com API update object structure, containing fields like body, creator, replies, and associated assets.

See also

https://developer.monday.com/api-reference/reference/updates#fields

Parameters:
assets: list[Asset] | None = None

The update’s assets/files

body: str = ''

The update’s body

created_at: str = ''

The update’s creation date. Returned as YYYY-MM-DDTHH:MM:SS

creator: User | None = None

The update’s creator

creator_id: str = ''

The update’s creator unique identifier

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Update

Parameters:

data (dict[str, Any])

id: str = ''

The update’s unique identifier

item_id: str = ''

The update’s item unique identifier

parent_id: str = ''

The update’s parent unique identifier

replies: list[Update] | None = None

The update’s replies

text_body: str = ''

The update’s text body

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

updated_at: str = ''

The update’s last update date. Returned as YYYY-MM-DDTHH:MM:SS

User Types

class User(account=None, birthday='', country_code='', created_at='', current_language='', email='', enabled=False, id='', is_admin=False, is_guest=False, is_pending=False, is_view_only=False, is_verified=False, join_date='', last_activity='', location='', mobile_phone='', name='', out_of_office=None, phone='', photo_original='', photo_small='', photo_thumb='', photo_tiny='', sign_up_product_kind='', teams=None, time_zone_identifier='', title='', url='', utc_hours_diff=0)[source]

Bases: object

Represents a Monday.com user with their profile and account information.

This dataclass maps to the Monday.com API user object structure, containing fields like name, email, profile photos, teams, and account settings.

See also

https://developer.monday.com/api-reference/reference/users#fields

Parameters:
account: Account | None = None

The user’s account

birthday: str = ''

The user’s date of birth. Returned as YYYY-MM-DD

country_code: str = ''

The user’s country code

created_at: str = ''

The user’s creation date. Returned as YYYY-MM-DD

current_language: str = ''

The user’s language

email: str = ''

The user’s email

enabled: bool = False

Returns True if the user is enabled

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

User

Parameters:

data (dict[str, Any])

id: str = ''

The user’s unique identifier

is_admin: bool = False

Returns True if the user is an admin

is_guest: bool = False

Returns True if the user is a guest

is_pending: bool = False

Returns True if the user is pending (did not yet confirm the email)

is_verified: bool = False

Returns True if the user verified their email

is_view_only: bool = False

Returns True if the user is only a viewer

join_date: str = ''

The date the user joined the account. Returned as YYYY-MM-DD

last_activity: str = ''

The last date and time the user was active. Returned as YYYY-MM-DDTHH:MM:SS

location: str = ''

The user’s location

mobile_phone: str = ''

The user’s mobile phone number

name: str = ''

The user’s name

out_of_office: OutOfOffice | None = None

The user’s out-of-office status

phone: str = ''

The user’s phone number

photo_original: str = ''

Returns the URL of the user’s uploaded photo in its original size

photo_small: str = ''

Returns the URL of the user’s uploaded photo in a small size (150x150 px)

photo_thumb: str = ''

Returns the URL of the user’s uploaded photo in a small thumbnail size (50x50 px)

photo_tiny: str = ''

Returns the URL of the user’s uploaded photo in tiny size (30x30 px)

sign_up_product_kind: str = ''

The product the user first signed up to

teams: list[Team] | None = None

The user’s teams

time_zone_identifier: str = ''

The user’s time zone identifier

title: str = ''

The user’s title

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

url: str = ''

The user’s profile URL

utc_hours_diff: int = 0

The user’s UTC time difference in hours

class OutOfOffice(active=False, disable_notifications=False, end_date='', start_date='', type=None)[source]

Bases: object

Type definition for monday.com API user out of office settings

Parameters:

  • active (bool)

  • disable_notifications (bool)

  • end_date (str)

  • start_date (str)

  • type (Literal['family_time', 'focus_mode', 'on_break', 'out_of_office', 'out_sick', 'working_from_home', 'working_outside'] | None)

active: bool = False

Returns True if the out of office status is in effect

disable_notifications: bool = False

Returns True if the user has notifications disabled

end_date: str = ''

Out of office end date. Returned as YYYY-MM-DDTHH:MM:SS

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

OutOfOffice

Parameters:

data (dict[str, Any])

start_date: str = ''

Out of office start date. Returned as YYYY-MM-DDTHH:MM:SS

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

type: Optional[Literal['family_time', 'focus_mode', 'on_break', 'out_of_office', 'out_sick', 'working_from_home', 'working_outside']] = None

Out of office type

Workspace Types

class Workspace(boards=None, created_at='', description='', id='', kind='', name='', owners=None, picture_url='', settings_str='', state='', subscribers=None, teams=None, updated_at='')[source]

Bases: object

Represents a Monday.com workspace with its boards and members.

This dataclass maps to the Monday.com API workspace object structure, containing fields like name, description, boards, owners, and subscribers.

See also

https://developer.monday.com/api-reference/reference/workspaces#fields

Parameters:
boards: list[Board] | None = None

The workspace’s boards

created_at: str = ''

The workspace’s creation date. Returned as YYYY-MM-DDTHH:MM:SS

description: str = ''

The workspace’s description

classmethod from_dict(data)[source]

Create from dictionary.

Return type:

Workspace

Parameters:

data (dict[str, Any])

id: str = ''

The workspace’s unique identifier

kind: str = ''

The workspace’s kind

name: str = ''

The workspace’s name

owners: list[User] | None = None

The workspace’s owners

picture_url: str = ''

The workspace’s picture URL

settings_str: str = ''

The workspace’s settings as a JSON string

state: str = ''

The workspace’s state

subscribers: list[User] | None = None

The workspace’s subscribers

teams: list[User] | None = None

The workspace’s teams

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

updated_at: str = ''

The workspace’s last update date. Returned as YYYY-MM-DDTHH:MM:SS

Column Input Types

These dataclasses provide type-safe ways to set column values when updating items via the Monday.com API.

For example:

from monday.types.column_inputs import DateInput, StatusInput, TextInput, NumberInput

# Update multiple column values at once
await client.items.change_column_values(
   item_id=123456789,
   column_values=[
      DateInput('date_column_id', '2024-01-15', '14:30:00'),
      StatusInput('status_column_id', 'Working on it'),
      TextInput('text_column_id', 'Updated content'),
      NumberInput('number_column_id', 42.5)
   ]
)
class CheckboxInput(column_id, checked)[source]

Bases: object

Represents a checkbox column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • checked (bool) – Whether the checkbox is checked

Example

checkbox_val = CheckboxInput('unique_column_id', True)

await client.items.change_column_values(
    item_id=123456789, column_values=checkbox_val
)
checked: bool

Whether the checkbox is checked

column_id: str

The column’s unique identifier

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class CountryInput(column_id, country_code)[source]

Bases: object

Represents a country column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • country_code (str) – Country code in ISO 3166-1 alpha-2 format (e.g., ‘US’, ‘GB’)

Example

country_val = CountryInput('unique_column_id', 'US')

await client.items.change_column_values(
    item_id=123456789, column_values=country_val
)
__post_init__()[source]

Validate the country code.

Return type:

None

column_id: str

The column’s unique identifier

country_code: str

Country code in ISO 3166-1 alpha-2 format

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class DateInput(column_id, date, time=None)[source]

Bases: object

Represents a date column input value for Monday.com API operations.

Based on the Monday.com API documentation, date columns can be updated using either a simple string format (YYYY-MM-DD) or a JSON format with date and time.

Parameters:

  • column_id (str) – The column’s unique identifier

  • date (str) – The date in YYYY-MM-DD format

  • time (str | None) – Optional time in HH:MM:SS format (24-hour)

Example

# Simple date
date_val = DateInput('unique_column_id', '2024-01-15')

# Date with time (use UTC timezone)
date_val = DateInput('unique_column_id', '2024-01-15', '14:30:00')

# Use in change_column_values
await client.items.change_column_values(
    item_id=123456789, column_values=date_val
)
__post_init__()[source]

Validate the date and time format.

Return type:

None

column_id: str

The column’s unique identifier

date: str

The date in YYYY-MM-DD format

time: str | None = None

MM:SS format (24-hour)

Type:

Optional time in HH

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class DropdownInput(column_id, label)[source]

Bases: object

Represents a dropdown column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • label (str | list[str]) – The dropdown option label

Example

dropdown_val = DropdownInput('unique_column_id', 'Option 1')

await client.items.change_column_values(
    item_id=123456789, column_values=dropdown_val
)
column_id: str

The column’s unique identifier

label: str | list[str]

The dropdown option label or list of labels

to_dict()[source]

Convert to dictionary for API requests.

Monday.com expects dropdown values as an array under the ‘labels’ key (for label text) or ‘ids’ (for numeric IDs). This helper uses ‘labels’ when strings are provided; to use IDs, pass a dictionary directly.

Return type:

dict[str, Any]

class EmailInput(column_id, email, text=None)[source]

Bases: object

Represents an email column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • email (str) – The email address

  • text (str | None) – The display text (optional, defaults to email)

Example

email_val = EmailInput(
    'unique_column_id', 'user@example.com', 'Contact User'
)

await client.items.change_column_values(
    item_id=123456789, column_values=email_val
)
column_id: str

The column’s unique identifier

email: str

The email address

text: str | None = None

The display text (optional, defaults to email)

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class HourInput(column_id, hour, minute)[source]

Bases: object

Represents an hour column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • hour (int) – The hour value (0-23)

  • minute (int) – The minute value (0-59)

Example

hour_val = HourInput('unique_column_id', 14, 30)  # 2:30 PM

await client.items.change_column_values(
    item_id=123456789, column_values=hour_val
)
__post_init__()[source]

Validate the hour and minute values.

Return type:

None

column_id: str

The column’s unique identifier

hour: int

The hour value (0-23)

minute: int

The minute value (0-59)

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class LinkInput(column_id, url, text=None)[source]

Bases: object

Represents a link column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • url (str) – The URL

  • text (str | None) – The display text (optional, defaults to URL)

Example

link_val = LinkInput(
    'unique_column_id', 'https://example.com', 'Example Website'
)

await client.items.change_column_values(
    item_id=123456789, column_values=link_val
)
column_id: str

The column’s unique identifier

text: str | None = None

The display text (optional, defaults to URL)

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

url: str

The URL

class LocationInput(column_id, address, latitude, longitude)[source]

Bases: object

Represents a location column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • address (str) – The address

  • latitude (float) – The latitude coordinate

  • longitude (float) – The longitude coordinate

Example

location_val = LocationInput(
    'unique_column_id', '123 Main St', 40.7128, -74.0060
)

await client.items.change_column_values(
    item_id=123456789, column_values=location_val
)
address: str

The address

column_id: str

The column’s unique identifier

latitude: float

The latitude coordinate

longitude: float

The longitude coordinate

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class LongTextInput(column_id, text)[source]

Bases: object

Represents a long text column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • text (str) – The long text content

Example

long_text_val = LongTextInput(
    'unique_column_id', 'This is a longer text content...'
)

await client.items.change_column_values(
    item_id=123456789, column_values=long_text_val
)
column_id: str

The column’s unique identifier

text: str

The long text content

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class NumberInput(column_id, number)[source]

Bases: object

Represents a number column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • number (float) – The numeric value

Example

num_val = NumberInput('unique_column_id', 42.5)

await client.items.change_column_values(
    item_id=123456789, column_values=num_val
)
column_id: str

The column’s unique identifier

number: float

The numeric value

to_str()[source]

Convert to string for API requests.

Return type:

str

class PeopleInput(column_id, person_ids=None, team_ids=None)[source]

Bases: object

Represents a people column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • person_ids (list[int] | None) – List of person IDs to assign

  • team_ids (list[int] | None) – List of team IDs to assign

Example

people_val = PeopleInput('unique_column_id', person_ids=[123, 456])

await client.items.change_column_values(
    item_id=123456789, column_values=people_val
)
__post_init__()[source]

Validate that at least one type of ID is provided.

Return type:

None

column_id: str

The column’s unique identifier

person_ids: list[int] | None = None

List of person IDs to assign

team_ids: list[int] | None = None

List of team IDs to assign

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class PhoneInput(column_id, phone_number, country_code='US')[source]

Bases: object

Represents a phone column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • phone_number (str) – The phone number

  • country_code (str) – Country code in ISO 3166-1 alpha-2 format (defaults to ‘US’)

Example

phone_val = PhoneInput('unique_column_id', '+1-555-123-4567', 'US')

await client.items.change_column_values(
    item_id=123456789, column_values=phone_val
)
__post_init__()[source]

Validate the country code.

Return type:

None

column_id: str

The column’s unique identifier

country_code: str = 'US'

Country code in ISO 3166-1 alpha-2 format

phone_number: str

The phone number

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class RatingInput(column_id, rating)[source]

Bases: object

Represents a rating column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • rating (int) – The rating value (0-5)

Example

rating_val = RatingInput('unique_column_id', 4)

await client.items.change_column_values(
    item_id=123456789, column_values=rating_val
)
__post_init__()[source]

Validate the rating is within the valid range.

Return type:

None

column_id: str

The column’s unique identifier

rating: int

The rating value (0-5)

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class StatusInput(column_id, label)[source]

Bases: object

Represents a status column input value for Monday.com API operations. You can pass either the index or the label value of the status you want to update. If the label is a number, send the index instead.

Parameters:

  • column_id (str) – The column’s unique identifier

  • label (str | int) – The status label text or the index value

Example

status_val = StatusInput('unique_column_id', 'Working on it')

await client.items.change_column_values(
    item_id=123456789, column_values=status_val
)
column_id: str

The column’s unique identifier

label: str | int

The status label text or the index value

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class TagInput(column_id, tag_id)[source]

Bases: object

Represents a tag column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • tag_id (int | list[int]) – The tag ID or list of tag IDs

Example

tag_val = TagInput('unique_column_id', 'important')

await client.items.change_column_values(
    item_id=123456789, column_values=tag_val
)
column_id: str

The column’s unique identifier

tag_id: int | list[int]

The tag ID or list of tag IDs

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class TextInput(column_id, text)[source]

Bases: object

Represents a text column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • text (str) – The text content

Example

text_val = TextInput('unique_column_id', 'This is some text content')

await client.items.change_column_values(
    item_id=123456789, column_values=text_val
)
column_id: str

The column’s unique identifier

text: str

The text content

to_str()[source]

Convert to string for API requests.

Return type:

str

class TimelineInput(column_id, from_date, to_date)[source]

Bases: object

Represents a timeline column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • from_date (str) – Start date in YYYY-MM-DD format

  • to_date (str) – End date in YYYY-MM-DD format

  • include_time – Whether to include time (defaults to True)

Example

timeline_val = TimelineInput('unique_column_id', '2024-01-01', '2024-01-31')

await client.items.change_column_values(
    item_id=123456789, column_values=timeline_val
)
__post_init__()[source]

Validate the date format.

Return type:

None

column_id: str

The column’s unique identifier

from_date: str

Start date in YYYY-MM-DD format

to_date: str

End date in YYYY-MM-DD format

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class WeekInput(column_id, start_date, end_date)[source]

Bases: object

Represents a week column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • start_date (str) – Start date in YYYY-MM-DD format

  • end_date (str) – End date in YYYY-MM-DD format

Example

week_val = WeekInput('unique_column_id', '2024-01-01', '2024-01-07')

await client.items.change_column_values(
    item_id=123456789, column_values=week_val
)
__post_init__()[source]

Validate the date format and that dates are 7 days apart.

Return type:

None

column_id: str

The column’s unique identifier

end_date: str

End date in YYYY-MM-DD format

start_date: str

Start date in YYYY-MM-DD format

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class WorldClockInput(column_id, timezone)[source]

Bases: object

Represents a world clock column input value for Monday.com API operations.

Parameters:

  • column_id (str) – The column’s unique identifier

  • timezone (str) – The timezone in continent/city format (e.g., ‘America/New_York’, ‘Europe/London’)

Example

world_clock_val = WorldClockInput('unique_column_id', 'America/New_York')

await client.items.change_column_values(
    item_id=123456789, column_values=world_clock_val
)
__post_init__()[source]

Validate the timezone is in valid continent/city format.

Return type:

None

column_id: str

The column’s unique identifier

timezone: str

The timezone in continent/city format

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

Column Default Types

These dataclasses are used to define default values when creating columns.

class StatusDefaults(labels)[source]

Bases: object

Default configuration for status columns.

Parameters:

labels (list[StatusLabel])

labels: list[StatusLabel]

List of status labels to create

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class StatusLabel(text, index)[source]

Bases: object

Represents a status label with its properties.

Parameters:
__post_init__()[source]

Validate the index is within the valid ranges.

Return type:

None

index: int

0-19, 101-110, 151-160). See Monday.com status colors for index to color mappings.

Type:

The label index which corresponds to its color (ranges

text: str

The label text

class DropdownDefaults(options)[source]

Bases: object

Default configuration for dropdown columns.

Parameters:

options (list[DropdownLabel])

options: list[DropdownLabel]

List of dropdown options to create

to_dict()[source]

Convert to dictionary for API requests.

Return type:

dict[str, Any]

class DropdownLabel(text, index=None)[source]

Bases: object

Represents a dropdown option with its properties.

Parameters:

  • text (str)

  • index (int | None)

index: int | None = None

The option index (auto-assigned if None)

text: str

The option text

Query Types

These dataclasses are used to build complex queries and filter data from the Monday.com API. They are primarily used with the boards.get_items() method to filter items based on column values, dates, text content, and other criteria.

For basic usage examples, see Filtering and Querying Items in the Usage documentation.

For example:

from monday.types.item import QueryParams, QueryRule, OrderBy
# Create a query to find items with status "Done" or "In Progress"
query_params = QueryParams(
   rules=[
      QueryRule(
         column_id='status',
         compare_value=['Done', 'In Progress'],
         operator='any_of'
      )
   ],
   operator='and',
   order_by=OrderBy(
      column_id='date',
      direction='desc'
   )
)
# Use the query parameters
items = await monday_client.items.query(query_params=query_params)