# pyuptimerobot2
[](https://badge.fury.io/py/pyuptimerobot2)
[](https://pypi.org/project/pyuptimerobot2/)
[](https://opensource.org/licenses/MIT)
A comprehensive Python client for UptimeRobot API v3. This library provides complete access to all UptimeRobot monitoring features including monitors, alert contacts, maintenance windows, and status pages.
## Features
- 🔧 **Complete API Coverage**: All UptimeRobot API v3 endpoints implemented
- 📊 **Monitor Management**: Create, read, update, delete monitors with full configuration
- 🔔 **Alert Contacts**: Email, SMS, webhook, Slack, Teams, and Twitter notifications
- 🔧 **Maintenance Windows**: Schedule maintenance periods to pause monitoring
- 📄 **Status Pages**: Create and manage public status pages
- 👤 **Account Management**: Access account details and API key information
- ⚡ **Rate Limit Handling**: Built-in awareness of UptimeRobot's rate limits
- 🛡️ **Error Handling**: Comprehensive error handling with descriptive messages
- 📝 **Type Hints**: Full type annotations for better IDE support
## Installation
```bash
pip install pyuptimerobot2
```
Or install from source:
```bash
git clone https://github.com/emadomedher/pyUptimerobot.git
cd pyuptimerobot2
pip install -r requirements.txt
pip install .
```
## Quick Start
### Basic Usage
```python
from uptimerobot_api import UptimeRobotClient
# Initialize the client with your API key
client = UptimeRobotClient(api_key="your_api_key_here")
try:
# Get all monitors
monitors = client.get_monitors()
print(f"Found {len(monitors['data'])} monitors")
# Create a new HTTP monitor
new_monitor = client.new_monitor(
friendly_name="My Website",
url="https://example.com",
type=1, # HTTP monitor
interval=300 # 5 minutes
)
print(f"Created monitor: {new_monitor}")
# Get account details
account = client.get_account_details()
print(f"Account: {account}")
finally:
client.close()
```
### Advanced Monitor Configuration
```python
from uptimerobot_api import UptimeRobotClient
client = UptimeRobotClient(api_key="your_api_key")
# Create a monitor with keyword monitoring
monitor = client.new_monitor(
friendly_name="API Health Check",
url="https://api.example.com/health",
type=2, # Keyword monitor
keyword_type=1, # Should contain keyword
keyword_value='"status":"healthy"',
interval=60, # Check every minute
timeout=10, # 10 second timeout
alert_contacts="12345-67890" # Alert contact IDs
)
print(f"Created keyword monitor: {monitor}")
```
### Alert Contact Setup
```python
from uptimerobot_api import UptimeRobotClient
client = UptimeRobotClient(api_key="your_api_key")
# Create a webhook alert contact
webhook = client.new_alert_contact(
friendly_name="Slack Webhook",
type=5, # Webhook
value="https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
)
# Create an email alert contact
email = client.new_alert_contact(
friendly_name="Admin Email",
type=1, # Email
value="admin@example.com"
)
print(f"Created webhook: {webhook}")
print(f"Created email: {email}")
```
## API Reference
### UptimeRobotClient
The main client class for interacting with UptimeRobot API.
#### Initialization
```python
client = UptimeRobotClient(api_key="your_api_key")
```
#### Monitor Methods
- `get_monitors(monitors=None, types=None, statuses=None, keyword=None, alert_contacts=None, logs=None, logs_limit=None, response_times=None, response_times_limit=None, response_times_average=None, response_times_start_date=None, response_times_end_date=None, offset=None, limit=None)`: Get monitors with filtering
- `new_monitor(friendly_name, url, type, sub_type=None, port=None, keyword_type=None, keyword_value=None, interval=None, timeout=None, alert_contacts=None, monitor_group_id=None)`: Create a new monitor
- `edit_monitor(id, friendly_name=None, url=None, type=None, interval=None, timeout=None, alert_contacts=None)`: Update a monitor
- `delete_monitor(id)`: Delete a monitor
- `reset_monitor(id)`: Reset monitor statistics
#### Alert Contact Methods
- `get_alert_contacts(alert_contacts=None)`: Get alert contacts
- `new_alert_contact(friendly_name, type, value)`: Create an alert contact
- `edit_alert_contact(id, friendly_name=None, type=None, value=None)`: Update an alert contact
- `delete_alert_contact(id)`: Delete an alert contact
#### Maintenance Window Methods
- `get_maintenance_windows(maintenance_windows=None)`: Get maintenance windows
- `new_maintenance_window(friendly_name, type, value, duration, start_time=None, status=None)`: Create a maintenance window
- `edit_maintenance_window(id, friendly_name=None, type=None, value=None, duration=None)`: Update a maintenance window
- `delete_maintenance_window(id)`: Delete a maintenance window
#### Status Page Methods
- `get_status_pages(status_pages=None)`: Get status pages
- `new_status_page(friendly_name, monitors)`: Create a status page
- `edit_status_page(id, friendly_name=None, monitors=None, status_page_password=None)`: Update a status page
- `delete_status_page(id)`: Delete a status page
#### Account Methods
- `get_account_details()`: Get account information
- `get_api_key_details()`: Get API key information
### Monitor Types
| Value | Type | Description |
|-------|------|-------------|
| 1 | HTTP(S) | Standard website monitoring |
| 2 | Keyword | Monitors for specific text content |
| 3 | Ping | ICMP ping monitoring |
| 4 | Port | TCP port monitoring |
| 5 | Heartbeat | Custom heartbeat monitoring |
### Monitor Statuses
| Value | Status | Description |
|-------|--------|-------------|
| 0 | Paused | Monitor is paused |
| 1 | Not checked yet | Monitor hasn't been checked |
| 2 | Up | Monitor is responding |
| 8 | Seems down | Monitor appears down |
| 9 | Down | Monitor is down |
### Alert Contact Types
| Value | Type | Description |
|-------|------|-------------|
| 1 | Email | Email notifications |
| 2 | SMS | SMS notifications |
| 3 | Twitter DM | Direct messages |
| 5 | Webhook | HTTP webhook |
| 6 | Push | Push notifications |
| 9 | Slack | Slack integration |
| 12 | Microsoft Teams | Teams integration |
## Rate Limits
UptimeRobot enforces rate limits based on your plan:
| Plan | Rate Limit |
|------|------------|
| **Free** | 10 requests/minute |
| **Pro** | (monitor count × 2) requests/minute, max 5000/minute |
The client includes rate limit information in response headers when available.
## Error Handling
```python
from uptimerobot_api import UptimeRobotClient
import requests
client = UptimeRobotClient(api_key="your_api_key")
try:
monitors = client.get_monitors()
print(f"Success: {monitors}")
except ValueError as e:
# API-specific errors (invalid API key, not found, etc.)
print(f"API Error: {e}")
except requests.RequestException as e:
# Network/connection errors
print(f"Network Error: {e}")
```
## Examples
See the `examples/` directory for complete usage examples:
- `basic_monitoring.py`: Basic monitor CRUD operations
- `alert_contacts.py`: Setting up various alert contact types
- `maintenance_windows.py`: Managing maintenance schedules
- `status_pages.py`: Creating and managing status pages
- `bulk_operations.py`: Performing operations on multiple monitors
### Basic Monitoring Example
```python
from uptimerobot_api import UptimeRobotClient
client = UptimeRobotClient(api_key="your_api_key")
# Get all monitors
monitors = client.get_monitors()
for monitor in monitors['data']:
print(f"Monitor: {monitor['friendly_name']} - Status: {monitor['status']}")
# Create a new monitor
new_monitor = client.new_monitor(
friendly_name="Production API",
url="https://api.example.com/health",
type=1,
interval=300
)
# Update the monitor
client.edit_monitor(
id=new_monitor['data']['id'],
friendly_name="Production API v2"
)
# Clean up
client.delete_monitor(new_monitor['data']['id'])
client.close()
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/emadomedher/pyUptimerobot.git
cd pyuptimerobot2
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Quality
```bash
# Format code
black .
# Lint code
flake8 .
# Type checking
mypy .
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Disclaimer
This library is not officially affiliated with or endorsed by UptimeRobot. Use this library at your own risk and in accordance with UptimeRobot's Terms of Service.
## Support
- 📖 [Documentation](https://github.com/emadomedher/pyUptimerobot#readme)
- 🐛 [Bug Reports](https://github.com/emadomedher/pyUptimerobot/issues)
- 💬 [Discussions](https://github.com/emadomedher/pyUptimerobot/discussions)
## Changelog
### [0.1.0] - 2025-11-03
- Initial release
- Complete UptimeRobot API v3 implementation
- Monitor management (CRUD operations)
- Alert contact management
- Maintenance window management
- Status page management
- Account information access
- Comprehensive error handling
- Rate limit awareness
Raw data
{
"_id": null,
"home_page": "https://github.com/emadomedher/pyUptimerobot",
"name": "pyuptimerobot2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "uptimerobot monitoring api client uptime pyuptimerobot2",
"author": "Emad O. Medher",
"author_email": "lsumedher@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/be/d6/2305b6df55ad5aeec225b0b88ae7f48d4a3fb2e74da4555a1b4eee9bbbdf/pyuptimerobot2-0.1.1.tar.gz",
"platform": null,
"description": "# pyuptimerobot2\n\n[](https://badge.fury.io/py/pyuptimerobot2)\n[](https://pypi.org/project/pyuptimerobot2/)\n[](https://opensource.org/licenses/MIT)\n\nA comprehensive Python client for UptimeRobot API v3. This library provides complete access to all UptimeRobot monitoring features including monitors, alert contacts, maintenance windows, and status pages.\n\n## Features\n\n- \ud83d\udd27 **Complete API Coverage**: All UptimeRobot API v3 endpoints implemented\n- \ud83d\udcca **Monitor Management**: Create, read, update, delete monitors with full configuration\n- \ud83d\udd14 **Alert Contacts**: Email, SMS, webhook, Slack, Teams, and Twitter notifications\n- \ud83d\udd27 **Maintenance Windows**: Schedule maintenance periods to pause monitoring\n- \ud83d\udcc4 **Status Pages**: Create and manage public status pages\n- \ud83d\udc64 **Account Management**: Access account details and API key information\n- \u26a1 **Rate Limit Handling**: Built-in awareness of UptimeRobot's rate limits\n- \ud83d\udee1\ufe0f **Error Handling**: Comprehensive error handling with descriptive messages\n- \ud83d\udcdd **Type Hints**: Full type annotations for better IDE support\n\n## Installation\n\n```bash\npip install pyuptimerobot2\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/emadomedher/pyUptimerobot.git\ncd pyuptimerobot2\npip install -r requirements.txt\npip install .\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom uptimerobot_api import UptimeRobotClient\n\n# Initialize the client with your API key\nclient = UptimeRobotClient(api_key=\"your_api_key_here\")\n\ntry:\n # Get all monitors\n monitors = client.get_monitors()\n print(f\"Found {len(monitors['data'])} monitors\")\n\n # Create a new HTTP monitor\n new_monitor = client.new_monitor(\n friendly_name=\"My Website\",\n url=\"https://example.com\",\n type=1, # HTTP monitor\n interval=300 # 5 minutes\n )\n print(f\"Created monitor: {new_monitor}\")\n\n # Get account details\n account = client.get_account_details()\n print(f\"Account: {account}\")\n\nfinally:\n client.close()\n```\n\n### Advanced Monitor Configuration\n\n```python\nfrom uptimerobot_api import UptimeRobotClient\n\nclient = UptimeRobotClient(api_key=\"your_api_key\")\n\n# Create a monitor with keyword monitoring\nmonitor = client.new_monitor(\n friendly_name=\"API Health Check\",\n url=\"https://api.example.com/health\",\n type=2, # Keyword monitor\n keyword_type=1, # Should contain keyword\n keyword_value='\"status\":\"healthy\"',\n interval=60, # Check every minute\n timeout=10, # 10 second timeout\n alert_contacts=\"12345-67890\" # Alert contact IDs\n)\n\nprint(f\"Created keyword monitor: {monitor}\")\n```\n\n### Alert Contact Setup\n\n```python\nfrom uptimerobot_api import UptimeRobotClient\n\nclient = UptimeRobotClient(api_key=\"your_api_key\")\n\n# Create a webhook alert contact\nwebhook = client.new_alert_contact(\n friendly_name=\"Slack Webhook\",\n type=5, # Webhook\n value=\"https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK\"\n)\n\n# Create an email alert contact\nemail = client.new_alert_contact(\n friendly_name=\"Admin Email\",\n type=1, # Email\n value=\"admin@example.com\"\n)\n\nprint(f\"Created webhook: {webhook}\")\nprint(f\"Created email: {email}\")\n```\n\n## API Reference\n\n### UptimeRobotClient\n\nThe main client class for interacting with UptimeRobot API.\n\n#### Initialization\n\n```python\nclient = UptimeRobotClient(api_key=\"your_api_key\")\n```\n\n#### Monitor Methods\n\n- `get_monitors(monitors=None, types=None, statuses=None, keyword=None, alert_contacts=None, logs=None, logs_limit=None, response_times=None, response_times_limit=None, response_times_average=None, response_times_start_date=None, response_times_end_date=None, offset=None, limit=None)`: Get monitors with filtering\n- `new_monitor(friendly_name, url, type, sub_type=None, port=None, keyword_type=None, keyword_value=None, interval=None, timeout=None, alert_contacts=None, monitor_group_id=None)`: Create a new monitor\n- `edit_monitor(id, friendly_name=None, url=None, type=None, interval=None, timeout=None, alert_contacts=None)`: Update a monitor\n- `delete_monitor(id)`: Delete a monitor\n- `reset_monitor(id)`: Reset monitor statistics\n\n#### Alert Contact Methods\n\n- `get_alert_contacts(alert_contacts=None)`: Get alert contacts\n- `new_alert_contact(friendly_name, type, value)`: Create an alert contact\n- `edit_alert_contact(id, friendly_name=None, type=None, value=None)`: Update an alert contact\n- `delete_alert_contact(id)`: Delete an alert contact\n\n#### Maintenance Window Methods\n\n- `get_maintenance_windows(maintenance_windows=None)`: Get maintenance windows\n- `new_maintenance_window(friendly_name, type, value, duration, start_time=None, status=None)`: Create a maintenance window\n- `edit_maintenance_window(id, friendly_name=None, type=None, value=None, duration=None)`: Update a maintenance window\n- `delete_maintenance_window(id)`: Delete a maintenance window\n\n#### Status Page Methods\n\n- `get_status_pages(status_pages=None)`: Get status pages\n- `new_status_page(friendly_name, monitors)`: Create a status page\n- `edit_status_page(id, friendly_name=None, monitors=None, status_page_password=None)`: Update a status page\n- `delete_status_page(id)`: Delete a status page\n\n#### Account Methods\n\n- `get_account_details()`: Get account information\n- `get_api_key_details()`: Get API key information\n\n### Monitor Types\n\n| Value | Type | Description |\n|-------|------|-------------|\n| 1 | HTTP(S) | Standard website monitoring |\n| 2 | Keyword | Monitors for specific text content |\n| 3 | Ping | ICMP ping monitoring |\n| 4 | Port | TCP port monitoring |\n| 5 | Heartbeat | Custom heartbeat monitoring |\n\n### Monitor Statuses\n\n| Value | Status | Description |\n|-------|--------|-------------|\n| 0 | Paused | Monitor is paused |\n| 1 | Not checked yet | Monitor hasn't been checked |\n| 2 | Up | Monitor is responding |\n| 8 | Seems down | Monitor appears down |\n| 9 | Down | Monitor is down |\n\n### Alert Contact Types\n\n| Value | Type | Description |\n|-------|------|-------------|\n| 1 | Email | Email notifications |\n| 2 | SMS | SMS notifications |\n| 3 | Twitter DM | Direct messages |\n| 5 | Webhook | HTTP webhook |\n| 6 | Push | Push notifications |\n| 9 | Slack | Slack integration |\n| 12 | Microsoft Teams | Teams integration |\n\n## Rate Limits\n\nUptimeRobot enforces rate limits based on your plan:\n\n| Plan | Rate Limit |\n|------|------------|\n| **Free** | 10 requests/minute |\n| **Pro** | (monitor count \u00d7 2) requests/minute, max 5000/minute |\n\nThe client includes rate limit information in response headers when available.\n\n## Error Handling\n\n```python\nfrom uptimerobot_api import UptimeRobotClient\nimport requests\n\nclient = UptimeRobotClient(api_key=\"your_api_key\")\n\ntry:\n monitors = client.get_monitors()\n print(f\"Success: {monitors}\")\n\nexcept ValueError as e:\n # API-specific errors (invalid API key, not found, etc.)\n print(f\"API Error: {e}\")\n\nexcept requests.RequestException as e:\n # Network/connection errors\n print(f\"Network Error: {e}\")\n```\n\n## Examples\n\nSee the `examples/` directory for complete usage examples:\n\n- `basic_monitoring.py`: Basic monitor CRUD operations\n- `alert_contacts.py`: Setting up various alert contact types\n- `maintenance_windows.py`: Managing maintenance schedules\n- `status_pages.py`: Creating and managing status pages\n- `bulk_operations.py`: Performing operations on multiple monitors\n\n### Basic Monitoring Example\n\n```python\nfrom uptimerobot_api import UptimeRobotClient\n\nclient = UptimeRobotClient(api_key=\"your_api_key\")\n\n# Get all monitors\nmonitors = client.get_monitors()\nfor monitor in monitors['data']:\n print(f\"Monitor: {monitor['friendly_name']} - Status: {monitor['status']}\")\n\n# Create a new monitor\nnew_monitor = client.new_monitor(\n friendly_name=\"Production API\",\n url=\"https://api.example.com/health\",\n type=1,\n interval=300\n)\n\n# Update the monitor\nclient.edit_monitor(\n id=new_monitor['data']['id'],\n friendly_name=\"Production API v2\"\n)\n\n# Clean up\nclient.delete_monitor(new_monitor['data']['id'])\nclient.close()\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/emadomedher/pyUptimerobot.git\ncd pyuptimerobot2\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack .\n\n# Lint code\nflake8 .\n\n# Type checking\nmypy .\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis library is not officially affiliated with or endorsed by UptimeRobot. Use this library at your own risk and in accordance with UptimeRobot's Terms of Service.\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://github.com/emadomedher/pyUptimerobot#readme)\n- \ud83d\udc1b [Bug Reports](https://github.com/emadomedher/pyUptimerobot/issues)\n- \ud83d\udcac [Discussions](https://github.com/emadomedher/pyUptimerobot/discussions)\n\n## Changelog\n\n### [0.1.0] - 2025-11-03\n- Initial release\n- Complete UptimeRobot API v3 implementation\n- Monitor management (CRUD operations)\n- Alert contact management\n- Maintenance window management\n- Status page management\n- Account information access\n- Comprehensive error handling\n- Rate limit awareness\n",
"bugtrack_url": null,
"license": null,
"summary": "Python client for UptimeRobot API v3",
"version": "0.1.1",
"project_urls": {
"Bug Reports": "https://github.com/emadomedher/pyUptimerobot/issues",
"Documentation": "https://github.com/emadomedher/pyUptimerobot#readme",
"Homepage": "https://github.com/emadomedher/pyUptimerobot",
"Source": "https://github.com/emadomedher/pyUptimerobot"
},
"split_keywords": [
"uptimerobot",
"monitoring",
"api",
"client",
"uptime",
"pyuptimerobot2"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "85e2f901ad97794232a3b6de8a11f0535a40f4f010829c9e0bf80bd87f6af8dd",
"md5": "c2228693cab696f52e4890910a4f4436",
"sha256": "a9609e1d9f61cf8d481657326e05790175d981ddc2e8381d2f5106bf180a4a93"
},
"downloads": -1,
"filename": "pyuptimerobot2-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2228693cab696f52e4890910a4f4436",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5530,
"upload_time": "2025-11-03T10:18:22",
"upload_time_iso_8601": "2025-11-03T10:18:22.729241Z",
"url": "https://files.pythonhosted.org/packages/85/e2/f901ad97794232a3b6de8a11f0535a40f4f010829c9e0bf80bd87f6af8dd/pyuptimerobot2-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bed62305b6df55ad5aeec225b0b88ae7f48d4a3fb2e74da4555a1b4eee9bbbdf",
"md5": "e5bed7895e3ea0f95b7f3de07b379667",
"sha256": "af3a2786bdfe6e5bd4ecf451deb79941c938719c9f50da5b1f49d3ee8cade00b"
},
"downloads": -1,
"filename": "pyuptimerobot2-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "e5bed7895e3ea0f95b7f3de07b379667",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5967,
"upload_time": "2025-11-03T10:18:23",
"upload_time_iso_8601": "2025-11-03T10:18:23.773914Z",
"url": "https://files.pythonhosted.org/packages/be/d6/2305b6df55ad5aeec225b0b88ae7f48d4a3fb2e74da4555a1b4eee9bbbdf/pyuptimerobot2-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 10:18:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "emadomedher",
"github_project": "pyUptimerobot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
}
],
"lcname": "pyuptimerobot2"
}
JSON
