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.

POST /api/watch

Request body

{
  "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

{
  "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

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:

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

This is equivalent to calling:

# 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 for detailed error handling.

Next steps

Webhooks Guide

Receive change notifications

Pull-Based Monitoring

Poll for changes instead of webhooks

Schedule Endpoints

Manage your schedules

Strategy Endpoints

Refine extraction strategies

Need help?

Email me at mckinnon@meter.sh

​Watch Endpoint

​Create watch

​Request body

​Response

​Example

​What happens internally

​Managing your watch

​Error responses

​Next steps