> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uptimeio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Monitors

> Create a monitor in the dashboard or with the API, and understand every setting and default

A monitor watches one endpoint, service or scheduled job and opens an incident when it fails. This guide walks through creating an HTTP monitor in the dashboard and with the API. The other monitor types work the same way; see [Monitor Types](/monitors/http) for their specific settings.

## Before you start

* Create an account and verify your email address. Monitors cannot be created until the email is verified.
* Decide where alerts should go. You can add [notification destinations](/notifications/overview) now or after creating the monitor.
* Check your plan limits in [Plans & Features](/billing/plans): monitor count and minimum check interval.

## Create a monitor in the dashboard

<Steps>
  <Step title="Open the new monitor form">
    Click **Monitors** in the sidebar, then **Create Monitor**.
  </Step>

  <Step title="Enter the URL">
    HTTP is selected by default. Enter the full URL, for example `https://example.com/health`. The monitor name is derived from the URL and can be changed later from the monitor's edit page.

    To monitor something else (heartbeat, ping, TCP port, DNS), open **Monitoring something else?** and pick the type.
  </Step>

  <Step title="Review how often we check (optional)">
    Expand **How often we check**:

    * **Check Interval** slider. The default is **5 minutes**. The shortest interval you can save is set by your plan: 5 minutes on Free, 1 minute on Pro and Scale. The slider only offers intervals at or above your plan's minimum.
    * **Regions**. The default is automatic selection. Pro and Scale can choose specific locations (at least one). Free always uses automatic selection.
  </Step>

  <Step title="Review HTTP settings (optional)">
    Expand the HTTP section to change the method, expected status codes, headers, request body, redirects and SSL verification. See [Advanced options](#advanced-options).
  </Step>

  <Step title="Choose notification destinations (optional)">
    Expand **Notifications** and select the destinations that should be alerted. Verified destinations are pre-selected.
  </Step>

  <Step title="Create the monitor">
    Click **Create Monitor**. The first check runs shortly afterwards and the monitor page shows the status, response time and the location that ran the check.
  </Step>
</Steps>

## Create a monitor with the API

`POST /api/monitors` with a `read_write` API key (see [Authentication](/api-reference/authentication)):

```bash theme={null}
curl -X POST https://api.uptimeio.com/api/monitors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "type": "HTTP",
    "target": "https://api.example.com/health",
    "interval_seconds": 300,
    "timeout_ms": 10000,
    "monitoring_regions": [],
    "http_config": {
      "method": "GET",
      "expected_status_codes": [200]
    }
  }'
```

### Main request fields

| Field | Required | Default | Description |
| - | - | - | - |
| `name` | Yes | - | Up to 80 characters. |
| `type` | Yes | - | `HTTP`, `KEYWORD`, `ICMP`, `TCP`, `DNS` or `HEARTBEAT`. |
| `target` | Yes (not for `HEARTBEAT`) | - | URL, host or domain, depending on the type. |
| `interval_seconds` | Yes | - | 30 to 86,400 in the schema, but never below your plan's minimum (300 on Free, 60 on Pro and Scale). |
| `timeout_ms` | No | `10000` | 1,000 to 60,000. Must be shorter than the check interval. |
| `monitoring_regions` | Yes | - | `[]` for automatic selection, or location codes (Pro and Scale). Up to 10. |
| `http_config` | No | - | Method, headers, body, redirects, expected status codes, `slow_response_threshold_ms`. |
| `notification_target_ids` | No | - | Destination IDs that receive this monitor's alerts. |
| `group_id`, `tags` | No | - | Organise monitors. |

The full field reference is on the [Create Monitor](/api-reference/monitors/create) page.

## Choosing check settings

### Interval

| Plan | Shortest interval |
| - | - |
| Free | 5 minutes |
| Pro | 1 minute |
| Scale | 1 minute |

Use 5 minutes for non-critical sites and 1 minute for services where you need the fastest detection. A request below your plan's minimum is rejected with `INTERVAL_TOO_SHORT`.

### Timeout

The default is 30 seconds in the dashboard and 10 seconds through the API. The maximum is 60 seconds, through the API and the dashboard. The timeout must be shorter than the check interval, so a 60 second timeout needs an interval of 2 minutes or more. A timeout that is too short causes false failures on slow endpoints; too long delays failure detection.

### Locations

UptimeIO checks from multiple probe locations; see [Probe locations](/monitors/probe-locations) for the current list.

| Setting | Behaviour |
| - | - |
| **Automatic** (`monitoring_regions: []`) | UptimeIO chooses locations for you. The only option on Free. |
| **Specific locations** (Pro and Scale) | Select at least one. Regular checks run only from the selected locations. |

On Free, sending a non-empty `monitoring_regions` returns `403` with code `LOCATION_MONITORING_NOT_AVAILABLE`.

Whichever locations you select, an incident is only opened after failures are confirmed from multiple locations. See [Understanding Incidents](/essentials/understanding-incidents).

## Advanced options

<AccordionGroup>
  <Accordion title="HTTP method" icon="code">
    Default `GET`. Also available: `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` and `OPTIONS`. `HEAD` is faster because no body is downloaded.
  </Accordion>

  <Accordion title="Expected status codes" icon="check">
    Default: `[200]`. A check passes only when the response status is in the list. Add the codes your endpoint really returns, for example `[200, 201, 204]`.
  </Accordion>

  <Accordion title="Request headers and body" icon="heading">
    Add custom headers (for example `Authorization`) and a request body for `POST`, `PUT` and `PATCH`.
  </Accordion>

  <Accordion title="Follow redirects" icon="arrow-right">
    On by default, following up to 5 redirects (`max_redirects`, 0 to 10). Turn it off to detect unexpected redirects.
  </Accordion>

  <Accordion title="Authentication" icon="key">
    Send credentials in a request header, for example `Authorization: Bearer YOUR_TOKEN`. Use a dedicated, revocable credential for monitoring.
  </Accordion>

  <Accordion title="Slow response threshold" icon="clock">
    Set `slow_response_threshold_ms` to open a separate slow-response incident when responses exceed it. See [Understanding Incidents](/essentials/understanding-incidents#slow-response).
  </Accordion>

  <Accordion title="SSL certificate and domain expiry" icon="lock">
    Turn on certificate and domain expiry warnings in **SSL, domain & performance alerts** on the monitor form. See [Setting Up Alerts](/essentials/setting-up-alerts#certificate-and-domain-expiry-warnings).
  </Accordion>
</AccordionGroup>

## Test a monitor

After creating a monitor, use **Test Now** on its page to run an immediate check. The result shows success or failure, response time, status code and the location that ran it.

If a test fails, check the URL, expected status codes, timeout and authentication.

## Limits and pausing

* Every monitor that is not deleted counts towards your plan's monitor limit, **including paused monitors**. At the limit, creating a monitor returns `403` with code `MONITOR_LIMIT_REACHED`. Delete monitors or upgrade to free up room.
* Pausing stops checks. Resuming is refused with `MONITOR_LIMIT_REACHED` when your plan's limit of active monitors is reached.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Monitor shows Down but the site works">
    * Timeout too short for the endpoint.
    * Expected status codes do not match what the endpoint returns (the default is only `200`).
    * A firewall or rate limiter is blocking the UptimeIO user agent `UptimeIO-Monitor/1.0 (+https://uptimeio.com/monitoring-bot)`.
    * An invalid or expired certificate on the target. HTTPS checks fail when the certificate cannot be verified.
  </Accordion>

  <Accordion title="I cannot create a monitor">
    * `EMAIL_NOT_VERIFIED`: verify your email address.
    * `MONITOR_LIMIT_REACHED`: you are at your plan limit.
    * `INTERVAL_TOO_SHORT`: choose an interval at or above your plan minimum.
    * `VALIDATION_ERROR`: the target or another field is invalid. The message explains which.
  </Accordion>

  <Accordion title="Test passes but an incident opened">
    Incidents come from scheduled checks that fail and are then confirmed from multiple locations. Open the incident to see which checks failed and where.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Understanding Incidents" icon="triangle-exclamation" href="/essentials/understanding-incidents">
    How incidents are opened and resolved
  </Card>

  <Card title="Setting Up Alerts" icon="bell" href="/essentials/setting-up-alerts">
    Send alerts to email, Slack, webhooks and more
  </Card>

  <Card title="Monitor Types" icon="list" href="/monitors/http">
    Settings for each monitor type
  </Card>

  <Card title="Reading Metrics" icon="chart-line" href="/essentials/reading-metrics">
    Uptime and response time
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.