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

# Watchlist

> Subscribe to carriers and receive a daily diff when their status changes

The watchlist lets your account subscribe to specific carriers. After every nightly ETL, DotLookup compares the new data to the previous run and publishes diffs scoped to carriers your account watches — delivered as an [email digest](https://dotlookup.dev) or, for programmatic consumers, an [HMAC-signed webhook](/endpoints/watchlist-webhook).

<Note>
  All watchlist endpoints **require an API key**. See [Authentication](/guides/authentication).
</Note>

## List watched carriers

```
GET /v1/watchlist
```

Returns the carriers your account is currently watching.

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.dotlookup.dev/v1/watchlist \
    -H "X-API-Key: your_api_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "carriers": [
      {
        "dot_number": "2233855",
        "carrier_name": "ACME TRUCKING LLC",
        "status": "ACTIVE",
        "entity_type": "CARRIER",
        "city": "Dallas",
        "state": "TX",
        "created_at": "2026-04-12T15:30:00Z"
      }
    ],
    "total": 1
  }
  ```
</ResponseExample>

## Add carriers to the watchlist

```
POST /v1/watchlist
```

Add up to 50 DOT numbers in a single request. Adding a DOT that's already watched is a no-op.

<ParamField body="dot_numbers" type="string[]" required>
  Array of USDOT numbers (max 50 per request)
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.dotlookup.dev/v1/watchlist \
    -H "X-API-Key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{"dot_numbers": ["2233855", "1234567"]}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "added": 2,
    "skipped": 0,
    "status": "ok"
  }
  ```
</ResponseExample>

Returns `400 LIMIT_EXCEEDED` if the addition would exceed your account's watchlist cap.

## Remove a carrier

```
DELETE /v1/watchlist/{dot_number}
```

Removes a single DOT from the watchlist. Idempotent.

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE https://api.dotlookup.dev/v1/watchlist/2233855 \
    -H "X-API-Key: your_api_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  { "status": "removed" }
  ```
</ResponseExample>

## Check whether a carrier is watched

```
GET /v1/watchlist/check?dot_number=2233855
```

Lightweight check for one DOT — returns just a boolean. Useful for surfacing a "watching" toggle in a UI.

<ParamField query="dot_number" type="string" required>
  The carrier's USDOT number. **Singular** — pass one DOT per request.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.dotlookup.dev/v1/watchlist/check?dot_number=2233855" \
    -H "X-API-Key: your_api_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  { "watching": true }
  ```
</ResponseExample>

## Recent changes for watched carriers

```
GET /v1/watchlist/changes
```

Returns recent diffs for carriers on your watchlist. The shape mirrors [`GET /v1/changes/{etl_run_id}`](/endpoints/changes) — same `category`, `old_values`, `new_values` fields.

Use this for catch-up after a webhook delivery failure or when wiring up a new dashboard.

<Warning>
  This endpoint looks back **30 days**, not the 52-week window used by the [change feed](/endpoints/changes). If your integration has been offline longer than 30 days, those changes are not available here.
</Warning>

<ParamField query="since" type="string">
  Return only changes at or after this instant. Accepts RFC3339 (`2026-05-01T00:00:00Z`) or a bare date (`2026-05-01`), which is read as midnight UTC. Narrows within the 30-day window — it never reaches further back
</ParamField>

<ParamField query="category" type="string">
  Filter to a single change category, using the same values as the [change feed](/endpoints/changes)
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Results per page (max: 100)
</ParamField>

For an incremental feed, pass the `batch_ts` of the newest change you have already processed as `since` on the next poll.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.dotlookup.dev/v1/watchlist/changes?since=2026-05-01" \
    -H "X-API-Key: your_api_key_here"
  ```
</RequestExample>