# monday.com API Client
[](https://monday-client.readthedocs.io/en/latest/?badge=latest)
[](https://pypi.org/project/monday-client/)
[](https://pypi.org/project/monday-client/)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/LeetCyberSecurity/monday-client/issues)
[](https://github.com/LeetCyberSecurity/monday-client/commits/main)
This Python library provides an **asynchronous** client to interact with the [monday.com API](https://developer.monday.com/api-reference/reference/about-the-api-reference).
## Documentation
For detailed documentation, visit the [official documentation site](https://monday-client.readthedocs.io).
## Key Features
- **Asynchronous API calls** using `asyncio` and `aiohttp` for efficient I/O operations
- **Automatic handling of API rate limits and query limits** following monday.com's rate limit policies
- **Built-in retry logic** for handling rate limit exceptions, ensuring smooth operation without manual intervention
- **Type-safe column value updates** with dedicated input classes for all column types
- **Advanced filtering and querying** with QueryParams and QueryRule support
- **Fully customizable requests** with all monday.com method arguments and fields available
## Installation
```bash
pip install monday-client
```
## Usage
```python
import asyncio
from monday import MondayClient
async def main():
client = MondayClient(api_key='your_api_key_here')
# Query boards and items
boards = await client.boards.query(board_ids=[987654321, 876543210])
items = await client.items.query(item_ids=[123456789, 123456780])
# Access dataclass attributes
for board in boards:
print(f'Board: {board.name} (ID: {board.id})')
for item in items:
print(f'Item: {item.name} (ID: {item.id})')
asyncio.run(main())
```
### Use predefined field sets for more data
```python
import asyncio
from monday import MondayClient
from monday.fields import BoardFields, ItemFields
async def main():
client = MondayClient(api_key='your_api_key_here')
# Get detailed board information
detailed_boards = await client.boards.query(
board_ids=[987654321, 876543210],
fields=BoardFields.DETAILED # Includes: id name state board_kind description
)
# Get boards with items
boards_with_items = await client.boards.query(
board_ids=[987654321, 876543210],
fields=BoardFields.ITEMS # Includes: id name items_count items_page
)
asyncio.run(main())
```
See [Fields Reference](https://monday-client.readthedocs.io/en/latest/fields.html) in the documentation for more info.
You can also use custom field strings for specific needs:
```python
custom_boards = await client.boards.query(
board_ids=[987654321],
fields='id name state type url items_count update { body }'
)
custom_items = await client.items.query(
item_ids=[123456789],
fields='id name created_at updated_at column_values { id text }'
)
```
### Use QueryParams and QueryRule to filter data
```python
import asyncio
from monday import MondayClient, QueryParams, QueryRule
async def main():
client = MondayClient(api_key='your_api_key_here')
# Filter 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'
)
item_lists = await client.boards.get_items(
board_ids=[987654321, 876543210],
query_params=query_params,
fields='id name column_values { id text column { title } } '
)
# Access dataclass attributes from filtered results
for item_list in item_lists:
print(f'Board {item_list.board_id}:')
for item in item_list.items:
print(f' - {item.name} (ID: {item.id})')
asyncio.run(main())
```
### Use type-safe input classes to update column values
```python
import asyncio
from monday import MondayClient
from monday.types import DateInput, StatusInput, TextInput
async def main():
client = MondayClient(api_key='your_api_key_here')
# Create a new item
new_item = await client.items.create(
board_id=987654321,
item_name='New Task',
group_id='topics'
)
await client.items.change_column_values(
item_id=new_item.id,
column_values=[
StatusInput('status', 'Working on it'),
TextInput('text', 'Task description'),
DateInput('date', '2024-01-15', '14:30:00')
]
)
asyncio.run(main())
```
### Asynchronous Operations
All methods provided by the `MondayClient` are asynchronous and should be awaited. This allows for efficient concurrent execution of API calls.
### Rate Limiting and Retry Logic
The client automatically handles rate limiting in compliance with monday.com's API policies. When a rate limit is reached, the client will wait for the specified reset time before retrying the request. This ensures that your application doesn't need to manually handle rate limit exceptions and can operate smoothly.
### Error Handling
Custom exceptions are defined for handling specific error cases:
- `MondayAPIError`: Raised when an error occurs during API communication with monday.com
- `PaginationError`: Raised when item pagination fails during a request
- `QueryFormatError`: Raised when there is a query formatting error
- `ComplexityLimitExceeded`: Raised when the complexity limit and max retries are exceeded
- `MutationLimitExceeded`: Raised when the mutation limit and max retries are exceeded
### Logging
The client uses a logger named `monday` for all logging operations. By default, logging is suppressed. To enable logging:
```python
import logging
from monday import MondayClient
# Remove the default NullHandler and add a real handler
monday_logger = logging.getLogger('monday')
for handler in monday_logger.handlers[:]:
if isinstance(handler, logging.NullHandler):
monday_logger.removeHandler(handler)
if not monday_logger.handlers:
handler = logging.StreamHandler()
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
monday_logger.addHandler(handler)
client = MondayClient('your_api_key')
```
## Testing
This project uses `pytest` for testing and `ruff` for code quality. For development and testing, install with development dependencies:
```bash
pip install -e ".[dev]"
```
### Quick Test Commands
```bash
# Run all tests
pytest tests/
# Run only unit tests
pytest tests/ -m unit
# Run integration tests (requires API key)
pytest tests/ -m "integration and not mutation"
# Run mutation tests (requires API key)
pytest tests/ -m mutation
# Run with logging
pytest tests/ --logging=debug
```
See [docs/TESTING.md](docs/TESTING.md) for detailed testing documentation, configuration, and best practices.
## Development
This project uses these Python development tools:
- **ruff**: Fast Python linter and formatter (replaces autopep8, isort, pylint)
- **basedpyright**: Type checking
- **pre-commit**: Git hooks for code quality
### Quick Development Commands
```bash
# Create virtual environment
python -m venv .venv
# Activate virtual environment (Linux/macOS)
source .venv/bin/activate
# Or on Windows
# .venv\Scripts\activate
# Install development dependencies
pip install --upgrade pip setuptools wheel
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
# Format and lint code
ruff format monday tests
ruff check monday tests
# Fix code automatically
ruff check --fix monday tests
ruff format monday tests
# Run type checking
basedpyright
# Run all quality checks
ruff format monday tests
ruff check monday tests
basedpyright
```
## Contributing
Contributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/LeetCyberSecurity/monday-client) or see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## Support
For questions or support, open an issue on [GitHub Issues](https://github.com/LeetCyberSecurity/monday-client/issues).
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](https://github.com/LeetCyberSecurity/monday-client/blob/main/LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "monday-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "monday, monday.com, api, client, async, rate-limiting, complexity-limiting",
"author": null,
"author_email": "Dan Hollis <dh@leetsys.com>",
"download_url": "https://files.pythonhosted.org/packages/3d/85/c66cf2a809dbadeac6235d8b280054e0a5848093369639d18db9274d5908/monday_client-0.1.76.tar.gz",
"platform": null,
"description": "# monday.com API Client\n\n[](https://monday-client.readthedocs.io/en/latest/?badge=latest)\n[](https://pypi.org/project/monday-client/)\n[](https://pypi.org/project/monday-client/)\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://github.com/LeetCyberSecurity/monday-client/issues)\n[](https://github.com/LeetCyberSecurity/monday-client/commits/main)\n\nThis Python library provides an **asynchronous** client to interact with the [monday.com API](https://developer.monday.com/api-reference/reference/about-the-api-reference).\n\n## Documentation\n\nFor detailed documentation, visit the [official documentation site](https://monday-client.readthedocs.io).\n\n## Key Features\n\n- **Asynchronous API calls** using `asyncio` and `aiohttp` for efficient I/O operations\n- **Automatic handling of API rate limits and query limits** following monday.com's rate limit policies\n- **Built-in retry logic** for handling rate limit exceptions, ensuring smooth operation without manual intervention\n- **Type-safe column value updates** with dedicated input classes for all column types\n- **Advanced filtering and querying** with QueryParams and QueryRule support\n- **Fully customizable requests** with all monday.com method arguments and fields available\n\n## Installation\n\n```bash\npip install monday-client\n```\n\n## Usage\n\n```python\nimport asyncio\n\nfrom monday import MondayClient\n\nasync def main():\n client = MondayClient(api_key='your_api_key_here')\n\n # Query boards and items\n boards = await client.boards.query(board_ids=[987654321, 876543210])\n items = await client.items.query(item_ids=[123456789, 123456780])\n\n # Access dataclass attributes\n for board in boards:\n print(f'Board: {board.name} (ID: {board.id})')\n\n for item in items:\n print(f'Item: {item.name} (ID: {item.id})')\n\nasyncio.run(main())\n```\n\n### Use predefined field sets for more data\n\n```python\nimport asyncio\n\nfrom monday import MondayClient\nfrom monday.fields import BoardFields, ItemFields\n\nasync def main():\n client = MondayClient(api_key='your_api_key_here')\n\n # Get detailed board information\n detailed_boards = await client.boards.query(\n board_ids=[987654321, 876543210],\n fields=BoardFields.DETAILED # Includes: id name state board_kind description\n )\n\n # Get boards with items\n boards_with_items = await client.boards.query(\n board_ids=[987654321, 876543210],\n fields=BoardFields.ITEMS # Includes: id name items_count items_page\n )\n\nasyncio.run(main())\n```\n\nSee [Fields Reference](https://monday-client.readthedocs.io/en/latest/fields.html) in the documentation for more info.\n\nYou can also use custom field strings for specific needs:\n\n```python\ncustom_boards = await client.boards.query(\n board_ids=[987654321],\n fields='id name state type url items_count update { body }'\n)\n\ncustom_items = await client.items.query(\n item_ids=[123456789],\n fields='id name created_at updated_at column_values { id text }'\n)\n```\n\n### Use QueryParams and QueryRule to filter data\n\n```python\nimport asyncio\n\nfrom monday import MondayClient, QueryParams, QueryRule\n\nasync def main():\n client = MondayClient(api_key='your_api_key_here')\n\n # Filter items with status \"Done\" or \"In Progress\"\n query_params = QueryParams(\n rules=[\n QueryRule(\n column_id='status',\n compare_value=['Done', 'In Progress'],\n operator='any_of'\n )\n ],\n operator='and'\n )\n\n item_lists = await client.boards.get_items(\n board_ids=[987654321, 876543210],\n query_params=query_params,\n fields='id name column_values { id text column { title } } '\n )\n\n # Access dataclass attributes from filtered results\n for item_list in item_lists:\n print(f'Board {item_list.board_id}:')\n for item in item_list.items:\n print(f' - {item.name} (ID: {item.id})')\n\nasyncio.run(main())\n```\n\n### Use type-safe input classes to update column values\n\n```python\nimport asyncio\n\nfrom monday import MondayClient\nfrom monday.types import DateInput, StatusInput, TextInput\n\nasync def main():\n client = MondayClient(api_key='your_api_key_here')\n\n # Create a new item\n new_item = await client.items.create(\n board_id=987654321,\n item_name='New Task',\n group_id='topics'\n )\n\n await client.items.change_column_values(\n item_id=new_item.id,\n column_values=[\n StatusInput('status', 'Working on it'),\n TextInput('text', 'Task description'),\n DateInput('date', '2024-01-15', '14:30:00')\n ]\n )\n\nasyncio.run(main())\n```\n\n### Asynchronous Operations\n\nAll methods provided by the `MondayClient` are asynchronous and should be awaited. This allows for efficient concurrent execution of API calls.\n\n### Rate Limiting and Retry Logic\n\nThe client automatically handles rate limiting in compliance with monday.com's API policies. When a rate limit is reached, the client will wait for the specified reset time before retrying the request. This ensures that your application doesn't need to manually handle rate limit exceptions and can operate smoothly.\n\n### Error Handling\n\nCustom exceptions are defined for handling specific error cases:\n\n- `MondayAPIError`: Raised when an error occurs during API communication with monday.com\n- `PaginationError`: Raised when item pagination fails during a request\n- `QueryFormatError`: Raised when there is a query formatting error\n- `ComplexityLimitExceeded`: Raised when the complexity limit and max retries are exceeded\n- `MutationLimitExceeded`: Raised when the mutation limit and max retries are exceeded\n\n### Logging\n\nThe client uses a logger named `monday` for all logging operations. By default, logging is suppressed. To enable logging:\n\n```python\nimport logging\nfrom monday import MondayClient\n\n# Remove the default NullHandler and add a real handler\nmonday_logger = logging.getLogger('monday')\nfor handler in monday_logger.handlers[:]:\n if isinstance(handler, logging.NullHandler):\n monday_logger.removeHandler(handler)\n\nif not monday_logger.handlers:\n handler = logging.StreamHandler()\n formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')\n handler.setFormatter(formatter)\n monday_logger.addHandler(handler)\n\nclient = MondayClient('your_api_key')\n```\n\n## Testing\n\nThis project uses `pytest` for testing and `ruff` for code quality. For development and testing, install with development dependencies:\n\n```bash\npip install -e \".[dev]\"\n```\n\n### Quick Test Commands\n\n```bash\n# Run all tests\npytest tests/\n\n# Run only unit tests\npytest tests/ -m unit\n\n# Run integration tests (requires API key)\npytest tests/ -m \"integration and not mutation\"\n\n# Run mutation tests (requires API key)\npytest tests/ -m mutation\n\n# Run with logging\npytest tests/ --logging=debug\n```\n\nSee [docs/TESTING.md](docs/TESTING.md) for detailed testing documentation, configuration, and best practices.\n\n## Development\n\nThis project uses these Python development tools:\n\n- **ruff**: Fast Python linter and formatter (replaces autopep8, isort, pylint)\n- **basedpyright**: Type checking\n- **pre-commit**: Git hooks for code quality\n\n### Quick Development Commands\n\n```bash\n# Create virtual environment\npython -m venv .venv\n\n# Activate virtual environment (Linux/macOS)\nsource .venv/bin/activate\n# Or on Windows\n# .venv\\Scripts\\activate\n\n# Install development dependencies\npip install --upgrade pip setuptools wheel\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n\n# Format and lint code\nruff format monday tests\nruff check monday tests\n\n# Fix code automatically\nruff check --fix monday tests\nruff format monday tests\n\n# Run type checking\nbasedpyright\n\n# Run all quality checks\nruff format monday tests\nruff check monday tests\nbasedpyright\n```\n\n## Contributing\n\nContributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/LeetCyberSecurity/monday-client) or see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Support\n\nFor questions or support, open an issue on [GitHub Issues](https://github.com/LeetCyberSecurity/monday-client/issues).\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](https://github.com/LeetCyberSecurity/monday-client/blob/main/LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for interacting with the monday.com API. Respects monday.com API rate limits and query complexity limits.",
"version": "0.1.76",
"project_urls": {
"Bug Reports": "https://github.com/LeetCyberSecurity/monday-client/issues",
"Documentation": "https://monday-client.readthedocs.io/",
"Homepage": "https://github.com/LeetCyberSecurity/monday-client",
"Source": "https://github.com/LeetCyberSecurity/monday-client"
},
"split_keywords": [
"monday",
" monday.com",
" api",
" client",
" async",
" rate-limiting",
" complexity-limiting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ba177c43bb513a790c9d8e3dc04c3df1095f627dd8b4c69380b2bf278931b1a6",
"md5": "1ebcec75179b49504fa6af46218bdceb",
"sha256": "cb52bb2c30c4c82bc5d893067d9a8f3c9c31b4c2b271efba7c6301bd9caf8299"
},
"downloads": -1,
"filename": "monday_client-0.1.76-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1ebcec75179b49504fa6af46218bdceb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 123503,
"upload_time": "2025-07-16T03:06:32",
"upload_time_iso_8601": "2025-07-16T03:06:32.969765Z",
"url": "https://files.pythonhosted.org/packages/ba/17/7c43bb513a790c9d8e3dc04c3df1095f627dd8b4c69380b2bf278931b1a6/monday_client-0.1.76-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3d85c66cf2a809dbadeac6235d8b280054e0a5848093369639d18db9274d5908",
"md5": "e4d5f08698150aa1681a2a776357cfa1",
"sha256": "ec4e077b7b4b7823dd449e57b60790134c091f1ecb815da60fc171f88ecf86dd"
},
"downloads": -1,
"filename": "monday_client-0.1.76.tar.gz",
"has_sig": false,
"md5_digest": "e4d5f08698150aa1681a2a776357cfa1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 111354,
"upload_time": "2025-07-16T03:06:34",
"upload_time_iso_8601": "2025-07-16T03:06:34.239651Z",
"url": "https://files.pythonhosted.org/packages/3d/85/c66cf2a809dbadeac6235d8b280054e0a5848093369639d18db9274d5908/monday_client-0.1.76.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 03:06:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LeetCyberSecurity",
"github_project": "monday-client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "monday-client"
}
JSON
