---
title: "Watch a file or directory for changes."
method: POST
path: "/v1/sandboxes/{id}/files/watches"
tags: ["files"]
---

# Watch a file or directory for changes.

`POST /v1/sandboxes/{id}/files/watches`

## Request

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

Starts a watch in the sandbox and answers once it is watching, so nothing changed after the answer is missed. Read its events with GET .../watches/{watchId}/events (poll with a cursor, or follow=true for a stream). Default events are create, write, remove, rename (with oldPath) and chmod; access events are opt-in. Events are batched every batchMs with repeated writes folded into one event. A new directory under a recursive watch is scanned when it appears, so files made in it before its watch took effect are reported too. At most 4 watches per sandbox; each ends after timeoutMs, or runs until stopped when timeoutMs is zero. webhook: true also sends its changes to the account's webhooks as sandbox.files.changed events, so nothing has to read it. Needs the exec scope. Wakes a paused sandbox.

## Path parameters

- `id` string, required: Resource identifier (UUID).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `path` string, required: The directory to watch, absolute, e.g. /workspace/app.
  - `recursive` boolean: Watch every directory under it too. Default false.
  - `events` string[]: Only these event types. Default: all of create, write, remove, rename, chmod.
  - `include` string[]: Report only paths matching one of these globs, relative to path (`**/*.py`; a bare `*.py` matches at any depth).
  - `exclude` string[]: Skip paths matching these globs. A directory excluded (`node_modules`, `dist/**`) is not watched at all.
  - `batchMs` integer: Gather events this long and send them as one batch, folding repeated writes to a file into one event with a count. Default 100.
  - `timeoutMs` integer: The watch ends by itself after running this long; 0 lasts until stopped or the sandbox ends. Default 3600000 (1 h).
  - `maxWatches` integer: Directories watched at most; past it a `limit` notice. Default 10000.
  - `id` string: A watch's id.
  - `webhook` boolean: Also send its changes to the account's webhooks as sandbox.files.changed events, read by Runtime without waking the sandbox: at most one event every 2 s a watch, 16 such watches an account. Default false.

## Response `200`

Success

- object
  - `id` string, required
  - `path` string, required
  - `processId` string, required
  - `state` string, required
  - `startedAt` integer
  - `cursor` integer: Read events from here.
  - `watches` integer: Directories being watched.
  - `webhook` boolean: Its changes go to the account's webhooks.

## 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)