watch

Watch: one socket that says which of your objects changed, so what shows them reads them again instead of polling.

for message in noclick.watch(objects=["deployment", "domain"]):
    if message.type == "change":
        refresh(message.object, message.object_id)
    elif message.type == "reset" or (message.type == "ready" and not message.resumed):
        refresh_all()

A change names an object (as its read's object says it: deployment, channel, agent, ...) and its id, never its data: read it again. It is not the event log (noclick.Event, webhooks), which records what happened, with data, for 30 days and delivers each event at least once. A change is a hint, delivered at most once: re-read everything you show on reset, on a ready that didn't resume (the first one too, for anything you read before it), and on a slow timer of your own if you must never be stale.

Your key follows the account's objects, its users' included; acting for one user (user), only that user's. A server whose page should watch hands the page a token from watch_token (pass the page's origin); the page opens it with the TypeScript SDK's watch({ token }).

watch needs the websockets package: pip install "noclick[live]".

async *function watch(options?: WatchOptions): AsyncGenerator<WatchMessage>

Follow your objects' changes until signal aborts or you stop reading. Reconnects by itself (a new token each time), resuming after the last change it gave you; it throws only what can't be fixed by trying again: the token call refused (a revoked key, a scope the key lacks, a deployment where watching isn't available) or the room refusing two fresh tokens in a row (WatchRefused).

A change can be lost (a deploy, a dropped connection, a busy second), and nothing says so but these: read again what you show on reset, on a ready that didn't resume, and on a slow timer of your own if it must never be stale.

Parameters
options.objectsreadonly (WatchedObject | string)[]

Follow only these (default: every object the key may read).

options.userUserOption

Act for one of your users: follow only their objects.

(defaults to the current user)
options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

options.token() => Promise<{ url: string; token: string }>

Where a token comes from, when not this client: your own server's endpoint that calls watchToken.

options.onStatus(status: WatchStatus) => void

Where the socket stands, as it moves.

options.signalAbortSignal

Stops watching (the generator returns).

options.WebSockettypeof WebSocket

A WebSocket class, where the runtime has none of its own (Node before 22).

options.originstring

The page's origin the socket will come from (a browser sends its own).

Returns

WatchMessage values: ready as each connection opens, change, typing and reset.

Types
/** Where the socket stands: `connecting`, `live`, `reconnecting` (it will on its own), or `stopped`. */
type WatchStatus = "connecting" | "live" | "reconnecting" | "stopped";

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** What `watch` follows: each an object as its read names it. */
type WatchedObject =
  | "domain" | "deployment" | "repo" | "mcp_server" | "live_session" | "phone_call" | "workflow"
  | "durable_object_class" | "skill" | "memory" | "machine" | "sandbox" | "agent_move" | "connection" | "plan_usage"
  | "agent_trigger" | "approval" | "browser" | "agent" | "coding_agent" | "channel" | "workspace"
  | "workspace_resource" | "channel_sections" | "space_question";

watchToken

function watchToken(options?: WatchTokenOptions): Promise<WatchToken>

A single-use token for the watch socket (POST /v1/watch/tokens), for a page to open with watch({ token }).

Parameters
options.objectsreadonly (WatchedObject | string)[]

Follow only these (default: every object the key may read).

options.originstring

The page's origin the socket will come from (a browser sends its own).

options.userUserOption

Act for one of your users: follow only their objects.

(defaults to the current user)
options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

A WatchToken: the socket's url, the token, when it expires and when the connection it opens ends.

Types
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** What `watch` follows: each an object as its read names it. */
type WatchedObject =
  | "domain" | "deployment" | "repo" | "mcp_server" | "live_session" | "phone_call" | "workflow"
  | "durable_object_class" | "skill" | "memory" | "machine" | "sandbox" | "agent_move" | "connection" | "plan_usage"
  | "agent_trigger" | "approval" | "browser" | "agent" | "coding_agent" | "channel" | "workspace"
  | "workspace_resource" | "channel_sections" | "space_question";

WatchReady

interface WatchReady

The socket is open: resumed when it carried on from the last change you got, so nothing was missed.

Attributes
resumedboolean
type"ready"

WatchChange

interface WatchChange

An object changed: read it again.

Attributes
idstring

This change's place in the stream (what a reconnect resumes after).

atDate | null
objectWatchedObject | string
objectIdstring | null

Its id; null for a coding_agent change that may be any of them.

statusstring | null

Its status as its read gave it then (advisory: the read is the truth); null once it's gone.

parent{ object: string; id: string } | null

What it belongs to: a deployment's project, a call's phone number, a trigger's agent, ...

changestring | null

What moved: an agent's turn, step, definition, ...; a channel's message, reaction, thread, ...

versionnumber | null

A workflow's graph version now.

workspaceIdstring | null
messageIdstring | null
threadIdstring | null
rawJsonObject

The response JSON exactly as the API sent it.

type"change"
Types
/** What `watch` follows: each an object as its read names it. */
type WatchedObject =
  | "domain" | "deployment" | "repo" | "mcp_server" | "live_session" | "phone_call" | "workflow"
  | "durable_object_class" | "skill" | "memory" | "machine" | "sandbox" | "agent_move" | "connection" | "plan_usage"
  | "agent_trigger" | "approval" | "browser" | "agent" | "coding_agent" | "channel" | "workspace"
  | "workspace_resource" | "channel_sections" | "space_question";

type JsonObject = { [key: string]: unknown };

WatchTyping

interface WatchTyping

Someone started or stopped typing in a channel you read (never sent to the one typing).

Attributes
channelIdstring
workspaceIdstring | null
userIdstring

Who: a user's id, or account for the account's owner.

typingboolean
rawJsonObject

The response JSON exactly as the API sent it.

type"typing"
Types
type JsonObject = { [key: string]: unknown };

WatchReset

interface WatchReset

Too much changed to say each: read again everything you show.

Attributes
type"reset"

WatchToken

interface WatchToken

A single-use token for the socket at url, good until expiresAt.

Attributes
urlstring
tokenstring
expiresAtDate | null
connectionEndsAtDate | null

When the connection it opens ends (watch then reconnects with a new token).

objectsstring[]
userIdstring | null

The user whose objects it follows; null for the account's.

originstring | null

The page's origin the socket must come from, when one was given.

rawJsonObject

The response JSON exactly as the API sent it.

Types
type JsonObject = { [key: string]: unknown };

WatchRefused

class WatchRefused extends NoClickError

The error that ends a watch: the room refused it again right after a fresh token (access ended).

retryAfterTypeScript only

retryAfter: number | undefined

Seconds the server asked us to wait (from Retry-After), when it did.

errorTypestaticTypeScript only

static errorType: string

WatchMessage

const WatchMessage: any

What watch yields; a message type this version doesn't know is skipped, so the stream can grow.