---
title: "Poll a watch for new changes (priced per delta)"
method: GET
path: "/api/v1/watch/{id}"
tags: ["Watch"]
---

# Poll a watch for new changes (priced per delta)

`GET /api/v1/watch/{id}`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/watch/{id}`
- Auth: HTTP bearer

Poll new parcel_deeds / parcel_permits changes matching the watch since its per-source cursor. preview=true returns the pending count + exact price + a masked sample (FREE, no cursor move). A paid poll debits the credit balance PER DELTA (clamp($0.05 x event-strength, $0.02, $0.20), capped $20/poll), advances the cursor, and returns the full deltas. A poll with no new changes is free. Insufficient balance -> 402. Parcel watches match on the full parcel identity; each delta carries `canonical_id` + `match_basis`. A watch created before 2026-09-22 whose stored bare ids are ambiguous reports them in `identity_issues` (not matched) on every poll. Deed parties (grantor / grantee names and addresses, prior / new owner) are people data, delivered to accounts only: a poll paid with a credit token and no account (no API key, no signed-in session) receives the deltas with those fields set to null and a top-level `people_fields` marker (see PeopleFieldsWithheld). The events themselves (what changed, where, when, for how much) are unchanged.

## Path parameters

- `id` string, required

## Query parameters

- `preview` boolean
- `limit` integer

## Headers

- `X-CREDIT-TOKEN` string, required

## Response `200`

Deltas delivered (paid), a free preview, or a free empty poll.

- object
  - `deltas` object[]
  - `people_fields` PeopleFieldsWithheld: Additive marker on a record (or list) whose people fields were withheld because the caller has no PropRaven account. People fields are owner names, owner mailing / owner-address columns, entity principals, recorded-document party names and addresses (grantor/grantee, buyer/seller, prior/new owner), permit applicant names and the resolved `owner_contact` block. Withheld keys are kept and set to null (lists of people records become []), so the record's shape does not change. Send an API key (`Authorization: Bearer pz_...`) or call from a signed-in session; on the paid products a settled x402 payment or a prepaid credit debit also delivers people data.
    - `status` 'withheld', required
    - `code` 'account_required', required
    - `reason` 'people_data_requires_account', required
    - `note` string, required

## Other responses

- `400`: A query or body parameter is invalid. Nothing was read or charged.
- `401`: Missing/invalid credit token.
- `402`: Insufficient credit balance for the pending deltas; top up and re-poll.
- `404`: Watch not found.
- `405`: The endpoint exists but does not support this method. `Allow` lists the methods it does.
- `500`: Unexpected server error. The body never carries database or driver text.

---

[API](https://skmtc.dev/propraven/apis/propraven-api.md) · [All operations](https://skmtc.dev/propraven/apis/propraven-api/llms.txt) · [OpenAPI document](https://skmtc.dev/propraven/apis/propraven-api/revisions/37f8158c4eda?raw)