# Create a monitor

`POST /v1/monitors`

**Price:** Free.

**Rate limit:** Counts as 1 request against your per-minute rate limit.

**MCP tool:** `create_monitor`, only on [MCP](/mcp) connections granted monitor or webhook access.

Requires an API key, sent as `Authorization: Bearer <key>`.

## Request

```bash
curl --request POST \
  --url https://api.weirapp.io/v1/monitors \
  --header "Authorization: Bearer $WEIR_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name":"…","target":"…"}'
```

### Body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | yes | 1–120 chars |
| `target` | object or object or object or object or object or object or object | yes | What the monitor watches. `search` runs a keyword search across sources; `subreddit` watches one community, with a keyword or without; `x_user` watches one account's posts; `reddit_thread` and `x_thread` watch one conversation for new replies. Identifiers are normalised, so a pasted URL, an `r/` prefix, or an `@` handle are all accepted. |
| `schedule` | string | no | `manual`, `hourly`, `daily`, `weekly`, default `"daily"` |
| `webhookId` | string or null | no |  |

## Response

The created monitor.

### `201`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.id` | string (uuid) | yes |  |
| `data.name` | string | yes |  |
| `data.target` | object or object or object or object or object or object or object | yes | What the monitor watches. `search` runs a keyword search across sources; `subreddit` watches one community, with a keyword or without; `x_user` watches one account's posts; `reddit_thread` and `x_thread` watch one conversation for new replies. Identifiers are normalised, so a pasted URL, an `r/` prefix, or an `@` handle are all accepted. |
| `data.sources` | array of string | yes |  |
| `data.schedule` | string | yes | `manual`, `hourly`, `daily`, `weekly` |
| `data.status` | string | yes | `active`, `paused`, `archived` |
| `data.webhookId` | string or null | yes |  |
| `data.lastRunAt` | string or null | yes |  |
| `data.nextRunAt` | string or null | yes |  |
| `data.createdAt` | string (date-time) | yes |  |
| `data.updatedAt` | string (date-time) | yes |  |
| `meta` | object | yes |  |
| `meta.requestId` | string | yes |  |

## Errors

| Status | Meaning | What to do |
| --- | --- | --- |
| `400` | The request failed validation. | The request was malformed. The `details` object names the field. |
| `401` | The API key is missing, malformed, expired, or revoked. | The key is missing, malformed, revoked, or expired. |
| `402` | The account is out of credit. Not retryable: this cannot clear until the billing period resets or the plan changes. | Out of credits. **Never retry.** Only a person can clear it, by adding credits at https://weirapp.io/dashboard/billing. Retrying never will. |
| `403` | The API key does not carry the scope this route requires. | The key is valid but lacks the scope this operation needs. |
| `404` | The webhook does not exist in this account. | No such resource, or it is not public. |
| `409` | The tier's monitor limit was reached, or its schedules do not include hourly. `details.limit` says which ceiling. | The request conflicts with the current state of the resource. |
| `429` | The per-minute rate limit is exhausted. Retryable: wait for Retry-After and try again. | Rate limited. Retryable: wait for `Retry-After`, then try again. |
| `500` | An unexpected error occurred. | Something failed on our side. Retryable with backoff. |