Submitting Jobs

A job is a uniquely identifiable client-facing unit of work. Every job has a canonical job_id and maps to a single-node workflow under the hood.

Creating a Job

TypeScript

import { FabricClient } from "@fabric-platform/sdk";

const fabric = new FabricClient({ apiKey: "fab_xxx" });

const job = await fabric.createJob({
  modality: "text",
  tier: "basic",
  input: { prompt: "Summarize this article" },
  params: { temperature: 0.5 },
  organizationId: "<org-id>",
});
console.log(job.id, job.status);

Python

from fabric_platform import FabricClient

fabric = FabricClient(api_key="fab_xxx")

job = fabric.create_job(
    modality="text",
    tier="basic",
    input={"prompt": "Summarize this article"},
    params={"temperature": 0.5},
    organization_id="<org-id>",
)
print(job["id"], job["status"])

Rust

use fabric_sdk::FabricClient;

let client = FabricClient::new("http://localhost:3001", api_key)?;

let job = client.create_job(serde_json::json!({
    "modality": "text",
    "tier": "basic",
    "input": {"prompt": "Summarize this article"},
    "params": {"temperature": 0.5},
    "organization_id": "<org-id>"
})).await?;
println!("{} {}", job.id, job.status);

curl

curl -X POST http://localhost:3001/v1/jobs \
  -H 'Authorization: Bearer fab_xxx' \
  -H 'content-type: application/json' \
  -d '{
    "modality": "text",
    "tier": "basic",
    "input": {"prompt": "Summarize this article"},
    "params": {"temperature": 0.5},
    "organization_id": "<org-id>"
  }'

The response includes the canonical job_id you can use to track the job:

{
  "data": {
    "job_id": "job_01HXYZ...",
    "status": "pending",
    "workflow_run_id": "run_01HXYZ..."
  }
}

Job Lifecycle

Jobs progress through these states:

1. pending — Created, waiting for execution
2. started — Executor has claimed the job
3. completed — Finished successfully with output
4. failed — Execution failed after all retries

Querying Jobs

TypeScript

// Get a specific job
const job = await fabric.getJob("<job-id>");

// List all jobs
const jobs = await fabric.listJobs();

// Get job usage/cost
const usage = await fabric.getJobUsage("<job-id>");

Python

# Get a specific job
job = fabric.get_job("<job-id>")

# List all jobs
jobs = fabric.list_jobs()

# Get job usage/cost
usage = fabric.get_job_usage("<job-id>")

Rust

// Get a specific job
let job = client.get_job("<job-id>").await?;

// List all jobs
let jobs = client.list_jobs().await?;

// Get job usage/cost
let usage = client.get_job_usage("<job-id>").await?;

curl

# Get a specific job
curl http://localhost:3001/v1/jobs/<job-id>

# List all jobs
curl http://localhost:3001/v1/jobs

# Get job usage/cost
curl http://localhost:3001/v1/jobs/<job-id>/usage

Idempotency

Fabric supports idempotent job submission to prevent duplicate work from retries or network failures.

Include an idempotency_key in the request:

TypeScript

const job = await fabric.createJob({
  modality: "text",
  input: { prompt: "Generate a summary" },
  organizationId: "<org-id>",
  idempotencyKey: "client-request-abc-123",
});

Python

job = fabric.create_job(
    modality="text",
    input={"prompt": "Generate a summary"},
    organization_id="<org-id>",
    idempotency_key="client-request-abc-123",
)

Rust

let job = client.create_job(serde_json::json!({
    "modality": "text",
    "input": {"prompt": "Generate a summary"},
    "organization_id": "<org-id>",
    "idempotency_key": "client-request-abc-123"
})).await?;

curl

curl -X POST http://localhost:3001/v1/jobs \
  -H 'Authorization: Bearer fab_xxx' \
  -H 'content-type: application/json' \
  -d '{
    "modality": "text",
    "input": {"prompt": "Generate a summary"},
    "organization_id": "<org-id>",
    "idempotency_key": "client-request-abc-123"
  }'

Duplicate submissions with the same idempotency key return the original resource.

Cost Estimation

Before submitting a job, you can estimate its cost:

TypeScript

const estimate = await fabric.estimateCost({
  modality: "text",
  model: "gpt-4",
  input: { prompt: "Generate a summary" },
});

Python

estimate = fabric.estimate_cost(
    modality="text",
    model="gpt-4",
    input={"prompt": "Generate a summary"},
)

Rust

let estimate = client.estimate_cost(serde_json::json!({
    "modality": "text",
    "model": "gpt-4",
    "input": {"prompt": "Generate a summary"}
})).await?;

curl

curl -X POST http://localhost:3001/v1/providers/estimate \
  -H 'content-type: application/json' \
  -d '{
    "modality": "text",
    "model": "gpt-4",
    "input": {"prompt": "Generate a summary"}
  }'

Local models (Ollama, Whisper) always return $0.00.

Job Events

Subscribe to real-time events for a specific job:

TypeScript

await fabric.streamEvents("<job-id>", (event) => {
  console.log(event.kind, event.payload);
});

Python

for event in fabric.stream_job_events("<job-id>"):
    print(event["kind"], event["payload"])

Rust

let mut stream = client.stream_job_events("<job-id>").await?;
while let Some(event) = stream.next().await {
    println!("{} {:?}", event.kind, event.payload);
}

curl

curl -N http://localhost:3001/v1/jobs/<job-id>/events

Job event types:

Event	Description
job.created	Job was created
job.started	Executor began processing
job.completed	Job finished with output
job.failed	Job execution failed

The per-job event stream replays all existing events on connect (catch-up), then streams live events as they occur.

Modalities

Jobs support these modalities, routed to the appropriate provider:

Modality	Description	Example Providers
text	Text generation and completion	OpenAI, Anthropic, Ollama
image	Image generation	OpenAI (DALL-E), ComfyUI
audio	Audio transcription	Whisper
embedding	Vector embeddings	OpenAI, Ollama (nomic-embed-text)

Tier Selection

Specify a tier preference to control provider selection:

• basic — Local/free providers (Ollama, Whisper, Echo)
• premium — Remote/paid providers (OpenAI, Anthropic)

If no tier is specified, the router selects by cost (cheapest first), then health status.