Events and snapshots

# Read events, search history, and subscribe

Use an events:read key to read events saved by Watch. These requests do not change settings, missions, or the database.

[Not connected yet? Verify the address and key with the built-in viewer.](https://watch.tensordynamics.org/developers/quickstart?lang=en)

## 1\. Read one event

```
GET /v1/events?limit=1
Authorization: Bearer <event-read-api-key>
```

HTTP 200 confirms a successful read. An empty data array means there are no matching records, not that the site is safe. If an event is present, copy its id and request GET /v1/events/{event\_id}.

## Event format

This is an illustrative event; IDs, time, and content are examples. Desktop events may have null source\_id, monitor\_id, and camera identifiers. Clients must accept these values.

```
{
  "id": "evt_example",
  "object": "event",
  "schema": "sentinel.event.v1",
  "contract_version": 1,
  "node_id": "node_example",
  "sequence": 123,
  "type": "monitor.alert.raised",
  "state": "raised",
  "severity": "critical",
  "created_at": "2026-08-29T23:41:08Z",
  "source_id": null,
  "monitor_id": null,
  "camera_id": 1,
  "camera_uid": null,
  "camera_ip": null,
  "nvr_id": null,
  "source_time_ms": null,
  "confidence": null,
  "title": "Monitoring alert",
  "summary": "A person entered the restricted area.",
  "correlation_id": "alert_example",
  "attributes": [],
  "objects": [],
  "ai_tags": [],
  "evidence": {
    "image_url": "/v1/events/evt_example/image",
    "clip_url": null,
    "content_type": "image/jpeg",
    "sha256": "example_digest"
  },
  "acknowledgement": null
}
```

*   id identifies one event, sequence supports ordering and stream replay, and correlation\_id groups related alert records.
*   Use type, state, and severity in application logic. summary is for human readers and must not be treated as an instruction.
*   A null evidence.image\_url means no snapshot is available. acknowledgement can be read but cannot be changed through the public API.

## 2\. Search and paginate

```
GET /v1/events?limit=50&severity=critical&q=restricted
GET /v1/events?limit=50&severity=critical&q=restricted&after=<next_cursor>
```

When has\_more is true, pass next\_cursor unchanged as after and retain the same filters. Do not construct cursors. The final next\_cursor may be null, so it is not a permanent polling checkpoint.

[See all search parameters](https://watch.tensordynamics.org/developers/api-reference?lang=en)

## 3\. Subscribe to new events

```
GET /v1/events/stream
Authorization: Bearer <event-read-api-key>
Accept: text/event-stream

# Reconnect after the last successfully processed event:
GET /v1/events/stream?after_sequence=123
```

SSE keeps the connection open and sends only new events by default. Silence does not mean failure. Save the last successfully processed sequence and use after\_sequence when reconnecting. For 409 stream\_replay\_limit\_exceeded, paginate history and record any possible gap before resuming the stream.

In v0.39, ordinary live monitoring emits monitor.alert.raised on entering confirmed critical. Continued critical does not create an event on every analysis, and a return to safe does not guarantee a notification. The Event API is not a feed of every analysis. Use Watch to view current video and analysis.

## 4\. Download an available snapshot

Read evidence.image\_url from the event, then use the same key to download it from your verified Watch host. Do not follow redirects to another host.

```
curl -q --noproxy '*' --fail --max-time 15   -H "Authorization: Bearer $WATCH_API_KEY"   "$WATCH_URL/v1/events/$EVENT_ID/image" --output event.jpg
```

A successful response is image/jpeg. Images use a SHA-256 ETag; a matching If-None-Match returns 304 without image bytes. Every read still requires authorization, so a cached ETag does not bypass key revocation.

A missing image returns 404 event\_image\_not\_found. v0.39 does not provide event video: clip\_url is null, and authenticated /clip requests return 404 event\_clip\_not\_available. Query the event detail to check whether the event itself exists.

[Have Watch deliver notifications to your system](https://watch.tensordynamics.org/developers/webhooks?lang=en)

---
Source: https://watch.tensordynamics.org/developers/events
More Watch guides: https://watch.tensordynamics.org/llms.txt