MondayClient

class MondayClient(config=None, *, api_key=None, url='https://api.monday.com/v2', version=None, headers=None, max_retries=4, transport='aiohttp')[source]

Bases: object

Client for interacting with the monday.com API. This client handles API requests, rate limiting, and pagination for monday.com’s GraphQL API.

Logging:

Each module in this library uses a module-level logger under the monday.* namespace (for example, monday.client). These loggers propagate to the root library logger monday. Configure logging either by working with the monday logger directly or by using helpers in monday.logging_utils.

Usage:
# Recommended: Using configuration object
>>> from monday import MondayClient, Config
>>> config = Config(api_key='your_api_key')
>>> monday_client = MondayClient(config)
>>> monday_client.boards.query(board_ids=987654321)

# Alternative: Using individual parameters
>>> monday_client = MondayClient(api_key='your_api_key')
>>> monday_client.boards.query(board_ids=987654321)
Parameters:

  • config (Config | None) – Config instance containing all client settings (recommended approach).

  • api_key (str | None) – The API key for authenticating with the monday.com API (alternative approach).

  • url (str) – The endpoint URL for the monday.com API.

  • version (str | None) – The monday.com API version to use.

  • headers (dict[str, Any] | None) – Additional HTTP headers used for API requests.

  • max_retries (int) – Maximum amount of retry attempts before raising an error.

  • transport (str)

logger: Logger = <Logger monday.client (WARNING)>

Module logger used by this class (e.g., monday.client).

Note

By default, a NullHandler is attached to the root monday logger to suppress output. To enable logs quickly in development, call:

from monday import enable_logging
enable_logging()  # Enable with default settings

To integrate with an existing logging configuration, call:

import logging.config
from monday import configure_for_external_logging

configure_for_external_logging()
logging.config.dictConfig({
    'version': 1,
    'handlers': {'console': {'class': 'logging.StreamHandler'}},
    'loggers': {'monday': {'level': 'INFO', 'handlers': ['console']}},
})

Other helpers:

from monday import set_log_level, disable_logging
set_log_level('DEBUG')  # Change level
disable_logging()       # Turn off completely
async post_request(query, variables=None)[source]

Executes an asynchronous post request to the monday.com API with rate limiting and retry logic.

Parameters:

  • query (str) – The GraphQL query string to be executed.

  • variables (dict[str, Any] | None) – Optional GraphQL variables to include with the query.

Return type:

dict[str, Any]

Returns:

A dictionary containing the response data from the API.

Raises:

Example

# Using config object (recommended)
>>> from monday import MondayClient, Config
>>> config = Config(api_key='your_api_key')
>>> monday_client = MondayClient(config)
>>> await monday_client.post_request(
...      query='query { boards (ids: 987654321) { id name } }'
... )

# Using individual parameters (alternative)
>>> monday_client = MondayClient(api_key='your_api_key')
>>> await monday_client.post_request(
...      query='query { boards (ids: 987654321) { id name } }'
... )
{
    "data": {
        "boards": [
            {
                "id": "987654321",
                "name": "Board 1"
            }
        ]
    },
    "account_id": 1234567
}

Note

This is a low-level method that directly executes GraphQL queries. In most cases, you should use the higher-level methods provided by the service classes instead, as they handle query construction and provide a more user-friendly interface.

use_api_key(api_key)[source]

Temporarily override the Authorization header for awaited calls within the context.

Example

async with client.use_api_key(‘integration_oauth_token’):

await client.webhooks.create(…)

Parameters:

api_key (str)

use_headers(headers)[source]

Temporarily override arbitrary headers for awaited calls within the context.

Example

async with client.use_headers({‘Authorization’: ‘token2’, ‘API-Version’: ‘2025-01’}):

await client.users.query(…)

Parameters:

headers (dict[str, Any])

Header overrides

To use a different API token for a subset of calls (e.g., integration OAuth tokens for webhooks), use the async context managers. Overrides are applied per awaited call and are safe under concurrency:

import asyncio

async def main():
   async with monday_client.use_api_key('integration_oauth_token'):
      await monday_client.webhooks.create(...)

asyncio.run(main())

You can also override arbitrary headers:

import asyncio

async def main():
   async with monday_client.use_headers({'Authorization': 'token2', 'API-Version': '2025-01'}):
      await monday_client.groups.create(...)

asyncio.run(main())

Services

The MondayClient provides access to various services for interacting with different aspects of the Monday.com API:

MondayClient.boards

Service for board-related operations.

Type: Boards

MondayClient.items

Service for item-related operations.

Type: Items

MondayClient.subitems

Service for subitem-related operations.

Type: Subitems

MondayClient.groups

Service for group-related operations.

Type: Groups

MondayClient.users

Service for user-related operations.

Type: Users

MondayClient.webhooks

Service for webhook-related operations.

Type: Webhooks