files

Watch a file or directory for changes.

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.

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

Path parameters

idstring required

Resource identifier (UUID).

Headers

Idempotency-Keystring

Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header.

Request body

pathstring required

The directory to watch, absolute, e.g. /workspace/app.

recursiveboolean

Watch every directory under it too. Default false.

eventsstring[]

Only these event types. Default: all of create, write, remove, rename, chmod.

includestring[]

Report only paths matching one of these globs, relative to path (**/*.py; a bare *.py matches at any depth).

excludestring[]

Skip paths matching these globs. A directory excluded (node_modules, dist/**) is not watched at all.

batchMsinteger

Gather events this long and send them as one batch, folding repeated writes to a file into one event with a count. Default 100.

timeoutMsinteger

The watch ends by itself after running this long; 0 lasts until stopped or the sandbox ends. Default 3600000 (1 h).

maxWatchesinteger

Directories watched at most; past it a limit notice. Default 10000.

idstring

A watch's id.

webhookboolean

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

Success

idstring required
pathstring required
processIdstring required
statestring required
startedAtinteger
cursorinteger

Read events from here.

watchesinteger

Directories being watched.

webhookboolean

Its changes go to the account's webhooks.

Changes

No recorded changes to this operation across all 1 revision of this API.