vitna.ai/docs/api/v1/engine/watches Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/api/v1/engine/watches
> Raw Markdown: https://vitna.ai/docs/api/v1/engine/watches.md
> Corpus index: https://vitna.ai/llms.txt

# Watches

What each workload is watching, and what has already fired.

```
GET /api/v1/watches
```

```bash
curl "https://vitna.ai/api/v1/watches?state=armed"
```

## Query parameters

| Parameter | Values |
|---|---|
| `workload` | A workload id |
| `state` | `armed`, `spent` |

## Response

```json
{
  "watches": [
    { "id": 3, "workloadId": "...", "kind": "price_move", "state": "armed",
      "params": { "minChangePct": 10 }, "firedAt": null,
      "watching": "..." }
  ],
  "meta": { "generatedAt": "...", "count": 5, "armed": 4, "spent": 1 }
}
```

## `watching`

A sentence describing the watch in words. It comes from the same
`describeTrigger` function the CLI prints, so the API and the operator's
register cannot describe one watch two different ways.

## Armed and spent

A trigger fires once and is then spent. It will not fire again until a decision
arms a new one.

That is what stops one volatile cell producing the same notification every hour
until somebody mutes it, and a muted watch is a watch nobody reads.

## Public today, scoped later

There is one org in the record and its decisions are the published case study,
so nothing here is anybody else's.

That stops being true the day a second org exists. Gating this is part of what
accounts means in the plan; the shape of the answer does not change, only who
may ask for it.

## Errors

| Status | Code | Cause |
|---|---|---|
| 400 | `bad_state` | Not `armed` or `spent` |
| 503 | `record_unavailable` | Watches are held in the record |

## Caching

`no-store`. An armed watch becomes a spent one at the end of any collector run,
and a minute of staleness reports that nothing has fired when something has.
Human Machine Shift+M