Job

Job

Represents a background job execution submitted via flow.job().

Methods

async status() -> JobStatus

Poll the current job status.

Returns: JobStatus object with state and results

Throws:

• Network/API errors

Example:

const job = await flow.job({ message: "hello" });
const status = await job.status();
console.log(`Job ${job.id}: ${status.state}`);

async wait(options?) -> ExecuteResult

Wait for the job to complete and return the result.

Parameters:

• timeoutMs (number, optional): Maximum time to wait in milliseconds. Default: undefined (wait indefinitely)

Returns: ExecuteResult when complete

Throws:

• TimeoutError if timeoutMs is exceeded
• Network/API errors

Example:

const job = await flow.job({ message: "hello" });
const result = await job.wait({ timeoutMs: 60_000 });  // Wait up to 60 seconds
console.log(result.output);

async cancel() -> void

Cancel a running job. Has no effect if the job is already complete.

Example:

const job = await flow.job({ message: "hello" });
await job.cancel();

Properties

id (string)

Unique job identifier.

Example:

const job = await flow.job({ message: "hello" });
console.log(job.id);  // e.g., "job_abc123..."

JobStatus (Type)

Job status information.

Attributes:

• id (string): Job ID
• state (string): One of "pending", "running", "completed", "failed", "cancelled"
• result (ExecuteResult | undefined): Final result if completed
• error (string | undefined): Error message if failed
• createdAt (string): ISO 8601 timestamp of job creation
• startedAt (string | undefined): ISO 8601 timestamp when job started
• completedAt (string | undefined): ISO 8601 timestamp when job completed
• progress (object | undefined): Progress metadata (implementation-specific)

Example:

const status = await job.status();
console.log(`Job ${status.id} is ${status.state}`);
if (status.state === "completed") {
  console.log(`Output: ${status.result?.output}`);
} else if (status.state === "failed") {
  console.log(`Error: ${status.error}`);
}

JobAccepted (Type)

Response when a job is successfully submitted (via flow.job()).

Attributes:

• id (string): Job ID (same as Job.id)
• state (string): Always "pending"

Example:

const job = await flow.job({ message: "hello" });
console.log(`Job ${job.id} accepted`);

Job Lifecycle

1. Submit via flow.job(...) → returns Job
2. Poll via job.status() → returns JobStatus with current state
3. Wait via job.wait() → blocks until complete
4. Cancel (optional) via job.cancel()
5. Retrieve result from JobStatus.result or job.wait() return value

Example:

// Submit
const job = await flow.job({ message: "long-running task" });
console.log(`Submitted: ${job.id}`);
 
// Poll
const status = await job.status();
console.log(`Status: ${status.state}`);
 
// Wait and get result
const result = await job.wait({ timeoutMs: 300_000 });  // 5 minutes
console.log(`Output: ${result.output}`);