Job System

Every AI inference on Socaity is a job. Understanding the job lifecycle will help you build reliable, efficient applications.

Coming soon: end-to-end streaming and status updates. The STREAMING state is in the canonical enum below, but transport support is still rolling out per model.

Job States

A job progresses through nine states defined by the APIJobStatus enum. Terminal states (FINISHED, FAILED, TIMEOUT, CANCELLED) are final and will not change.

PENDING

QUEUED

PROCESSING

STREAMING

FINISHED

FAILED

TIMEOUT

CANCELLED

UNKNOWN

State	Meaning	Terminal?	Result available?
PENDING	Job submitted, waiting to be validated and queued.	No	No
QUEUED	Validated and waiting for a GPU worker to pick it up.	No	No
PROCESSING	A GPU worker is actively processing the job.	No	No
STREAMING	Job is producing incremental results (LLM tokens, partial video).	No	No
FINISHED	Inference completed successfully. Result is available.	Yes	Yes
FAILED	An error occurred during inference. Check the error field.	Yes	No
TIMEOUT	Job exceeded the configured execution time limit.	Yes	No
CANCELLED	Job was cancelled by the client before or during processing.	Yes	No
UNKNOWN	Status string could not be mapped to a known state. Polling continues.	No	No

Lifecycle Diagram

PENDING

queued

PROCESSING

GPU active

FINISHED

result ready

Submitting a Job

Call the service directly to submit a job without blocking. The call returns a job object immediately.

from socaity import flux_schnell

flux = flux_schnell()

# Call returns immediately with a job handle (non-blocking)
job = flux(prompt="a neon city at night")
print(f"Job submitted: {job.job_id}")
print(f"Status: {job.response.status}")  # PENDING

# Block until done (SDK polls with back-off automatically)
result = job.get_result(timeout_s=120)
print(result)  # URL or file bytes

Polling Intervals

The SDK polls automatically with back-off. If you poll manually, use the recommended intervals below to avoid rate limits.

Phase	Recommended Interval	Notes
First 5s (PENDING)	500ms	Fast jobs may finish almost immediately.
5s – 30s	1s	Most image generation models complete in this window.
30s – 120s	3s	Video, large LLM, or long-audio tasks.
> 120s	10s	Very long jobs; consider webhooks instead.

import time

job = flux(prompt="a neon city")
interval = 0.5

while job.response.status not in ("FINISHED", "FAILED", "TIMEOUT", "CANCELLED"):
    time.sleep(interval)
    job.refresh()  # fetches latest status from API
    interval = min(interval * 1.5, 10)  # exponential back-off, cap at 10s
    print(f"  {job.response.status} — progress: {job.progress}")

if job.response.status == "FINISHED":
    print(job.result)
else:
    raise RuntimeError(f"Job failed: {job.error}")

Progress Reporting

The progress field is a float from 0.0 to 1.0. Not all models report granular progress — check for null.

job = flux(prompt="a cinematic landscape")

while not job.is_terminal:
    job.refresh()
    if job.progress is not None:
        filled = int(job.progress * 40)
        bar = "█" * filled + "░" * (40 - filled)
        print(f"\r[{bar}] {job.progress:.0%}", end="", flush=True)
    time.sleep(1)

print()  # newline after progress bar
print(job.result)

Webhook vs Polling

Aspect	Polling	Webhooks
Complexity	Polling loop	Requires public endpoint
Latency to result	Up to 1 poll interval delay	Near-instant delivery
API calls	N calls while waiting	0 calls while waiting
Best for	Scripts, notebooks, short jobs	Web apps, production pipelines
Error recovery	Retry the loop on failure	Need retry + idempotency logic

Cancellation

Jobs can be cancelled while in PENDING or PROCESSING state. You are not charged for cancelled jobs.

from socaity import flux_schnell

flux = flux_schnell()
job = flux(prompt="a neon city")

# Cancel the job if it's taking too long
if not job.is_terminal:
    cancelled = job.cancel()
    print(f"Cancel requested: {cancelled}")  # True if accepted
    job.refresh()
    print(f"Final status: {job.response.status}")  # CANCELLED or FINISHED

Cancellation is best-effort. If the GPU worker has already started the forward pass, the job may complete before the cancellation is processed. In that case, you will not be charged.

Serverless vs Dedicated GPU

Service Catalog