SDK reference · Resources
client.jobs
client.jobs.{ create, get, list, wait, cancel, events, stream, progress, report, artifacts }A job is one task run for one user: with tools only (execution_mode: "tools"), or on the user's computer ("computer"). It moves through queued, running and waiting_approval, and ends completed, failed, cancelled or timed_out.
create
create(input: JobInput, key?: string): Promise<Job>Submits a job. It starts queued; pass a key so a retried request doesn't start a second job.
Parameters
input.user_idstring- Who the job runs for.
input.taskstring- What to do, in plain language.
input.harnessstringoptional- The harness to run with, by name; the application's default otherwise. Settings the request leaves out come from it.
input.execution_mode"tools" | "computer"optional- Tools only, or on the user's computer (the harness's, or computer).
input.connection_idsstring[]optional- Connected accounts the job may use; it can use no others.
input.modelstringoptional- A managed model ID; the application's default otherwise.
input.web_accessbooleanoptional- Lets the job search and read the web.
keystringoptional- An idempotency key. Retrying with the same key and input returns the first result instead of acting twice.
Returns Promise<Job>
const job = await client.jobs.create(
{ user_id: user.id, task: "Summarize this week's invoices", execution_mode: "tools" },
"invoices-2026-09-30",
);get
get(id: string): Promise<Job>A job's status, result and error, plus cost_nano: what it has been billed so far.
Parameters
idstring- The job's ID (job_…).
Returns Promise<Job>
list
list(options?: ListOptions & { user_id?: string; failure_class?: string; harness_id?: string }): Promise<Page<Job>>The application's jobs, newest first.
Parameters
options{ after?: number; limit?: number }optional- Pagination: pass the previous page's next_cursor as after; limit is 1–200 (default 100).
options.user_idstringoptional- Only this user's jobs.
options.failure_classstringoptional- Only jobs that ended for this reason.
Returns Promise<Page<Job>>
wait
wait(id: string, options?: { intervalMs?: number; timeoutMs?: number }): Promise<Job>Polls the job until it ends and returns it. Throws TrickroomError with code wait_timeout if it's still running at timeoutMs.
Parameters
idstring- The job's ID.
options.intervalMsnumberoptional- Time between polls (default 2 s).
options.timeoutMsnumberoptional- Give up after this long (default 30 min).
Returns Promise<Job>
const done = await client.jobs.wait(job.id);
if (done.status === "completed") console.log(done.result_json);cancel
cancel(id: string): Promise<Job>Asks the job to stop; it ends cancelled after its current step.
Parameters
idstring- The job's ID.
Returns Promise<Job>
events
events(id: string, options?: ListOptions): Promise<Page<DeliveryEvent>>What the job did, in order: model turns, tool calls, approvals and the outcome. Page with after to follow a running job.
Parameters
idstring- The job's ID.
options{ after?: number; limit?: number }optional- Pagination: pass the previous page's next_cursor as after; limit is 1–200 (default 100).
Returns Promise<Page<DeliveryEvent>>
stream
stream(id: string, options?: StreamOptions): AsyncGenerator<JobEvent[]>The job's events as they are written, in batches, pushed over Server-Sent Events. It reconnects and resumes from the last event on its own.
Parameters
idstring- The job's ID.
options.afternumberoptional- The last sequence already seen (default 0).
options.signalAbortSignaloptional- Stops the stream.
Returns AsyncGenerator<JobEvent[]>
progress
progress(id: string, options?: StreamOptions): AsyncGenerator<JobUpdate>What to show someone waiting on the job: a short status such as "Searching your email" (progress), an approval it asks for (approval), and its end (finished, after which the generator returns).
Parameters
idstring- The job's ID.
options.afternumberoptional- The last sequence already seen (default 0).
options.signalAbortSignaloptional- Stops the stream.
Returns AsyncGenerator<JobUpdate>
for await (const update of client.jobs.progress(job.id)) {
if (update.type === "progress") showStatus(update.label);
if (update.type === "approval") showApproval(update.approvalId);
}report
report(id: string): Promise<Resource>A summary of the run: its outcome, evidence and checks.
Parameters
idstring- The job's ID.
Returns Promise<Resource>
artifacts
artifacts(id: string): Promise<Page>Files the job saved, such as JSON results and screenshots, each with a content URL.
Parameters
idstring- The job's ID.
Returns Promise<Page>