Job

Job (Sync)

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

Methods

status() -> JobStatus

Poll the current job status.

Returns: JobStatus object with state and results

Raises:

• Network/API errors

Example:

job = flow.job(message="hello")
status = job.status()
print(f"Job {job.id}: {status.state}")

wait(*, timeout_ms=None) -> ExecuteResult

Wait for the job to complete and return the result.

Parameters:

• timeout_ms (int, optional): Maximum time to wait in milliseconds. Default: None (wait indefinitely)

Returns: ExecuteResult when complete

Raises:

• TimeoutError if timeout_ms is exceeded
• Network/API errors

Example:

job = flow.job(message="hello")
result = job.wait(timeout_ms=60_000)  # Wait up to 60 seconds
print(result.output)

cancel() -> None

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

Example:

job = flow.job(message="hello")
job.cancel()

Properties

id (str)

Unique job identifier.

Example:

job = flow.job(message="hello")
print(job.id)  # e.g., "job_abc123..."

AsyncJob

Async equivalent of Job. All methods are awaitable.

Methods

async status() -> JobStatus

Poll the current job status (awaitable).

Example:

status = await job.status()

async wait(*, timeout_ms=None) -> ExecuteResult

Wait for the job to complete (awaitable).

Example:

result = await job.wait(timeout_ms=60_000)
print(result.output)

async cancel() -> None

Cancel a running job (awaitable).

Example:

await job.cancel()

JobStatus (Type)

Job status information.

Attributes:

• id (str): Job ID
• state (str): One of "pending", "running", "completed", "failed", "cancelled"
• result (ExecuteResult, optional): Final result if completed
• error (str, optional): Error message if failed
• created_at (str): ISO 8601 timestamp of job creation
• started_at (str, optional): ISO 8601 timestamp when job started
• completed_at (str, optional): ISO 8601 timestamp when job completed
• progress (dict, optional): Progress metadata (implementation-specific)

Example:

status = await job.status()
print(f"Job {status.id} is {status.state}")
if status.state == "completed":
    print(f"Output: {status.result.output}")
elif status.state == "failed":
    print(f"Error: {status.error}")

JobAccepted (Type)

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

Attributes:

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

Example:

job_accepted = await flow.job(message="hello")
print(f"Job {job_accepted.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
job = await flow.job(message="long-running task")
print(f"Submitted: {job.id}")
 
# Poll
status = await job.status()
print(f"Status: {status.state}")
 
# Wait and get result
result = await job.wait(timeout_ms=300_000)  # 5 minutes
print(f"Output: {result.output}")