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

# Watch

> Be told when one attribute of an entity changes, and pay for each change you are told about

## Overview

A watch says: tell me when this attribute of this entity changes, and charge me for each change you tell me about. Creating, holding, listing, changing and deleting a watch are free. Each change delivered is charged to your prepaid credits (see [Pricing](/pricing)).

Only some attributes can be watched. Today that is Government Solicitations and the US Treasury sanctions list. A watch on anything else is refused, and the response names what can be watched. A watch starts when you create it: earlier changes are what [Changes](/api-reference/changes) is for.

A delivered change has the fields of a Changes row: `changed_on`, `field`, `before`, `after`, `source` and `as_of`. An entity that stops being listed by the source is a change (`field` is `$entity`). When several fields of a value change at once, the change is one delivery with `field` `$` and the whole earlier and later value.

## Spending cap

Every watch states `max_spend`: at least the price of one change, at most 100 dollars. When the next change would pass it, or your credits cannot pay for it, the watch is paused with the reason (`cap` or `credits`) and you are told once.

Nothing is lost while a watch is paused. Changes that happen meanwhile are delivered and charged when the watch runs again. A watch paused for credits runs again by itself once your credits can pay. A watch paused at its cap runs again when you raise `max_spend`.

## Delivery

Each change is delivered once and charged once. It arrives as a `watch_change` notification (`GET /v1/tools/notifications`) and, if you gave a `webhook_url`, as a signed webhook sent after the charge. A webhook that keeps failing is retried and then given up on; it does not stop the notification, charge again or pause the watch. Every charge has a signed receipt.

The webhook body is JSON with `type` `watch.change`, `delivery_id`, `watch_id`, `entity_type`, `attribute`, `key`, `change`, `charged` and `receipt_id`, signed in the `X-OneShot-Signature` header with the secret returned when the webhook was set.

An agent may hold at most 100 watches that are not deleted.

## Create: `POST /v1/tools/watch`

<ParamField body="entity_type" type="string" required>
  The kind of entity, for example `company`
</ParamField>

<ParamField body="attribute" type="string" required>
  The attribute to watch, for example `sanctions`
</ParamField>

<ParamField body="key" type="string" required>
  The entity's key, the source's own identifier, as Changes takes it
</ParamField>

<ParamField body="max_spend" type="number" required>
  Most to spend on this watch, in dollars
</ParamField>

<ParamField body="webhook_url" type="string">
  HTTPS URL to send each change to. The response carries `webhook_secret` once.
</ParamField>

## List: `GET /v1/tools/watch`

Your watches with `status` (`running` or `paused`), `pause_reason` (`cap`, `credits` or `agent`) when paused, `spent`, `changes_delivered` and `last_delivery_at`.

## Change: `PATCH /v1/tools/watch/:id`

`max_spend`, `webhook_url` (a new URL gets a new secret; `null` stops sending) and `paused` (`true` pauses the watch, whatever its state; `false` resumes a watch you paused).

## Delete: `DELETE /v1/tools/watch/:id`

A deleted watch delivers and charges nothing more.

## Authentication

A signed agent proof (`X-Agent-ID`, `X-Agent-Proof`) with the `write` scope for create, change and delete, `read` for list. Watches commit your credits, so an access token cannot change them unless it comes from signing in with your OneShot account.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/watch \
    -H "Content-Type: application/json" \
    -H "X-Agent-ID: 0x..." \
    -H "X-Agent-Proof: <signed proof>" \
    -d '{
      "entity_type": "company",
      "attribute": "sanctions",
      "key": "12345",
      "max_spend": 1
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "id": "6f1c2a94-0d1e-4b53-9d0e-2f6f0c1f7a11",
      "entity_type": "company",
      "attribute": "sanctions",
      "key": "12345",
      "max_spend": 1,
      "spent": 0,
      "changes_delivered": 0,
      "status": "running",
      "pause_reason": null,
      "webhook_url": null,
      "price_per_change": 0.02,
      "last_delivery_at": null,
      "created_at": "2026-10-14T09:00:00.000Z",
      "updated_at": "2026-10-14T09:00:00.000Z"
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.