---
title: "A watch's events after a cursor, or follow them live."
method: GET
path: "/v1/sandboxes/{id}/files/watches/{watchId}/events"
tags: ["files"]
---

# A watch's events after a cursor, or follow them live.

`GET /v1/sandboxes/{id}/files/watches/{watchId}/events`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/sandboxes/{id}/files/watches/{watchId}/events`
- Auth: HTTP bearer

JSON: events after cursor, notices, nextCursor to pass next time, lostBytes when this reader fell more than 1 MiB behind (rescan), ended. waitMs (up to 8000) holds the call until something happens. follow=true (or Accept: application/x-ndjson) streams events until the watch ends; a stream ends with paused when the sandbox pauses (read again after it wakes: nothing is lost) or continue after 110 s, each with the cursor to resume from. Reading never wakes a paused sandbox.

## Path parameters

- `id` string, required: Resource identifier (UUID).
- `watchId` string, required: A watch's id.

## Query parameters

- `cursor` integer
- `waitMs` integer
- `follow` boolean

## Response `200`

Success

- object
  - `events` object[], required
    - `type` 'create' | 'write' | 'remove' | 'rename' | 'chmod' | 'access', required
    - `path` string, required
    - `isDir` boolean, required
    - `oldPath` string: rename: where it was.
    - `count` integer: write: writes folded into this event.
  - `notices` object[], required: overflow {dropped, reason: kernel|rate}: events were lost, rescan. limit {watches}: some directories are not watched. end {reason}: the watch stopped.
  - `nextCursor` integer, required
  - `lostBytes` integer, required: Events the sandbox discarded because this reader fell over 1 MiB behind.
  - `ended` boolean, required

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)