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.
Follow only these (default: every object the key may read).
Act for one of your users: follow only their objects.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
Where a token comes from, when not this client: your own server's endpoint that calls watchToken.
Where the socket stands, as it moves.
Stops watching (the generator returns).
A WebSocket class, where the runtime has none of its own (Node before 22).
The page's origin the socket will come from (a browser sends its own).
WatchMessage values: ready as each connection opens, change, typing and reset.
/** 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 }).
Follow only these (default: every object the key may read).
The page's origin the socket will come from (a browser sends its own).
Act for one of your users: follow only their objects.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A WatchToken: the socket's url, the token, when it expires and when the connection it opens ends.
/** `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 WatchReadyThe socket is open: resumed when it carried on from the last change you got, so nothing was missed.
| resumed | boolean | |
| type | "ready" |
WatchChange
interface WatchChangeAn object changed: read it again.
| id | string | This change's place in the stream (what a reconnect resumes after). |
| at | Date | null | |
| object | WatchedObject | string | |
| objectId | string | null | Its id; null for a |
| status | string | 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, ... |
| change | string | null | What moved: an agent's |
| version | number | null | A workflow's graph version now. |
| workspaceId | string | null | |
| messageId | string | null | |
| threadId | string | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| type | "change" |
/** 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 WatchTypingSomeone started or stopped typing in a channel you read (never sent to the one typing).
| channelId | string | |
| workspaceId | string | null | |
| userId | string | Who: a user's id, or |
| typing | boolean | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| type | "typing" |
type JsonObject = { [key: string]: unknown };WatchReset
interface WatchResetToo much changed to say each: read again everything you show.
| type | "reset" |
WatchToken
interface WatchTokenA single-use token for the socket at url, good until expiresAt.
| url | string | |
| token | string | |
| expiresAt | Date | null | |
| connectionEndsAt | Date | null | When the connection it opens ends (watch then reconnects with a new token). |
| objects | string[] | |
| userId | string | null | The user whose objects it follows; null for the account's. |
| origin | string | null | The page's origin the socket must come from, when one was given. |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };WatchRefused
class WatchRefused extends NoClickErrorThe error that ends a watch: the room refused it again right after a fresh token (access ended).
retryAfterTypeScript only
retryAfter: number | undefinedSeconds the server asked us to wait (from Retry-After), when it did.
errorTypestaticTypeScript only
static errorType: stringWatchMessage
const WatchMessage: anyWhat watch yields; a message type this version doesn't know is skipped, so the stream can grow.