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

# Watch a URL

> Poll a JSON API or a page on a schedule. Get an event only when the data changes.

A **Watch a URL** source (`http_poll`) sends a `GET` request to a URL on a schedule. It compares each response with the last one. It sends an event only when something changed, and it tells you what changed.

Use it for exchange rates, stock levels, tenders, status pages and partner APIs that send no webhooks.

<Info>Watch a URL sources need a Pro project.</Info>

## Modes

<Tabs>
  <Tab title="Document">
    Watch one value. When it changes, you get [`http_poll.changed`](/events/http-poll#http_poll-changed) with `before`, `after` and `changed_fields`.

    Example: watch the `rates` object of an exchange-rate API.

    | Field  | Value                              |
    | ------ | ---------------------------------- |
    | URL    | `https://api.example.com/v1/rates` |
    | Mode   | `document`                         |
    | Select | `$.rates`                          |

    If the response is not JSON, hooksnode watches the text. Leave **Select** empty.
  </Tab>

  <Tab title="Items">
    Watch a list. hooksnode keys each item by an ID field. You get one event for each item that was added, changed or removed:

    * [`http_poll.item.added`](/events/http-poll#http_poll-item-added)
    * [`http_poll.item.changed`](/events/http-poll#http_poll-item-changed)
    * [`http_poll.item.removed`](/events/http-poll#http_poll-item-removed)

    Example: watch new orders.

    | Field         | Value                                             |
    | ------------- | ------------------------------------------------- |
    | URL           | `https://shop.example.com/api/orders?status=open` |
    | Mode          | `items`                                           |
    | Items path    | `$.data`                                          |
    | ID field      | `id`                                              |
    | Ignore fields | `updated_at`                                      |
  </Tab>
</Tabs>

## Settings

| Setting       | Field              | Notes                                                                          |
| ------------- | ------------------ | ------------------------------------------------------------------------------ |
| URL           | `url`              | A public `http` or `https` URL. Private addresses are refused.                 |
| Mode          | `mode`             | `document` (default) or `items`.                                               |
| Select        | `select`           | Document mode. The path of the value to watch. Empty means the whole response. |
| Items path    | `items_path`       | Items mode. The path of the array.                                             |
| ID field      | `id_field`         | Items mode. Required.                                                          |
| Ignore fields | `ignore_fields`    | Up to 20 paths. Changes to these fields do not count. Use it for timestamps.   |
| Headers       | `headers`          | Up to 10 request headers, for example an API key. Stored encrypted.            |
| Interval      | `interval_seconds` | 60 to 86,400 seconds. Default 300.                                             |

### Paths

A path is a list of keys with dots: `$.data.items` or `data.items`. A number picks an array element: `$.data.0.price`. `$` or an empty path is the whole response.

## How it works

1. **Test first.** When you create or change the source, hooksnode runs a test poll. If it fails, nothing is saved.
2. **Baseline.** The first poll stores what it sees. It sends no events. A change to the URL, mode or paths takes a new baseline.
3. **Poll.** Each poll is a `GET` with `User-Agent: Hooksnode-Poller/1.0` and a 30 second timeout.
4. **Compare and send.** hooksnode stores each event first, then moves its cursor. A failed step leaves the cursor, and the next poll sends the same idempotency keys. You never get the same change twice.
5. **Check now.** Press **Check now** to poll at once.

## Limits

| Limit                | Value                                                                          |
| -------------------- | ------------------------------------------------------------------------------ |
| Response size        | 4 MiB                                                                          |
| Items in a list      | 5,000                                                                          |
| Events for each poll | 500 (the rest shows as a warning)                                              |
| Event size           | Over 3 MiB, `before`, `after` and `item` are removed and `truncated` is `true` |

The event shows the URL with no query string, because a query string can hold keys.

## Errors

* A `401` or `403` response sets the source to `error` and emails the project owner. Polling stops until you save settings that pass a test poll.
* Other errors back off. The interval doubles each time, up to 1 hour.