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

# Watch Endpoint

> One-step URL monitoring setup

# Watch Endpoint

Set up URL monitoring in a single API call. The watch endpoint combines strategy generation and schedule creation, eliminating the need for multi-step orchestration.

## Create watch

Create a new watch to monitor a URL for changes.

```http theme={null}
POST /api/watch
```

### Request body

```json theme={null}
{
  "url": "https://example.com/products",
  "description": "Extract product names and prices",
  "webhook_url": "https://your-app.com/webhooks/meter",
  "interval_seconds": 3600,
  "name": "Product Monitor"
}
```

| Field              | Type    | Required | Description                                                    |
| ------------------ | ------- | -------- | -------------------------------------------------------------- |
| `url`              | string  | Yes      | URL to monitor for changes                                     |
| `description`      | string  | Yes      | What to extract from the page                                  |
| `webhook_url`      | string  | No       | Webhook URL for change notifications                           |
| `interval_seconds` | integer | No       | How often to check (default: 3600, minimum: 60)                |
| `name`             | string  | No       | Name for the strategy (auto-generated if not provided)         |
| `webhook_metadata` | object  | No       | Custom JSON metadata included in every webhook payload         |
| `webhook_type`     | string  | No       | `standard` or `slack`. Auto-detected from URL if not specified |

### Response

```json theme={null}
{
  "strategy_id": "550e8400-e29b-41d4-a716-446655440000",
  "schedule_id": "880e8400-e29b-41d4-a716-446655440000",
  "preview_data": [
    {"name": "Product A", "price": "$19.99"},
    {"name": "Product B", "price": "$29.99"}
  ],
  "next_run_at": "2025-01-15T10:30:00Z"
}
```

| Field          | Type     | Description                              |
| -------------- | -------- | ---------------------------------------- |
| `strategy_id`  | UUID     | ID of the created extraction strategy    |
| `schedule_id`  | UUID     | ID of the created schedule               |
| `preview_data` | array    | Sample data extracted from the URL       |
| `next_run_at`  | datetime | When the first scheduled scrape will run |

### Example

```bash theme={null}
curl -X POST https://api.meter.sh/api/watch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "description": "Extract post titles, scores, and links",
    "webhook_url": "https://my-app.com/webhook",
    "interval_seconds": 1800
  }'
```

## What happens internally

The watch endpoint performs two operations in a single transaction:

1. **Generates a strategy** - Analyzes the page and creates extraction selectors using AI
2. **Creates a schedule** - Sets up recurring scrapes with your specified interval

This is equivalent to calling:

```bash theme={null}
# Step 1: Generate strategy
POST /api/strategies/generate

# Step 2: Create schedule with the strategy_id
POST /api/schedules
```

## Managing your watch

After creation, use the standard endpoints to manage your watch:

* **Update schedule**: `PATCH /api/schedules/{schedule_id}`
* **Pause/resume**: `PATCH /api/schedules/{schedule_id}` with `{"enabled": false}`
* **Get changes**: `GET /api/schedules/{schedule_id}/changes`
* **Delete**: `DELETE /api/schedules/{schedule_id}`
* **Refine strategy**: `POST /api/strategies/{strategy_id}/refine`

## Error responses

| Status | Description                                                   |
| ------ | ------------------------------------------------------------- |
| `400`  | Invalid request (missing required fields, interval too short) |
| `401`  | Invalid or missing API key                                    |
| `429`  | Rate limit exceeded (watch endpoint is rate-limited)          |
| `500`  | Internal server error                                         |
| `503`  | Service temporarily unavailable (AI service issues)           |

See [REST API Errors](/api-reference/rest/errors) for detailed error handling.

## Next steps

<CardGroup cols={2}>
  <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
    Receive change notifications
  </Card>

  <Card title="Pull-Based Monitoring" icon="download" href="/guides/pull-based-monitoring">
    Poll for changes instead of webhooks
  </Card>

  <Card title="Schedule Endpoints" icon="clock" href="/api-reference/rest/schedules">
    Manage your schedules
  </Card>

  <Card title="Strategy Endpoints" icon="brain" href="/api-reference/rest/strategies">
    Refine extraction strategies
  </Card>
</CardGroup>

## Need help?

Email me at [mckinnon@meter.sh](mailto:mckinnon@meter.sh)