valite
Sign inJoin waitlist
Docs navigation

Docs/API Reference/Jobs API

Jobs API

The analysis pipeline as HTTP: start a job kind against a workflow, poll until it finishes, read the artifact.

Job model

A job runs one pipeline stage for one workflow. The eight kinds, in pipeline order: profile, triage, bar, calibrate, replay, plan, validate, report. Jobs for the same workflow run serially; each writes a durable artifact that later stages read.

job object
{
  "id": "job_a1b2c3d4",
  "workflow": "support-triage",
  "kind": "replay",
  "status": "pending" | "running" | "succeeded" | "failed",
  "created_at": "2026-07-08T18:04:11Z",
  "finished_at": "2026-07-08T18:05:40Z",   // when finished
  "error": "...",                           // when failed
  "result": { ... }                         // when succeeded (and on budget-gate failures)
}

Start a job

POST/valite/api/workflows/{workflow}/jobs/{kind}

Returns 202 with the job object. The body is an optional parameters object (below); unknown fields are rejected. Unknown kind → 404; workflow names must match [A-Za-z0-9._-]{1,128} (account ids share the same alphabet). When an admin secret is configured, every control-plane request — this one included — requires x-valite-admin-secret, and the job is scoped to the organization in x-valite-account-id. The dashboard attaches both headers for you.

shell
curl -X POST \
  https://gateway.valite.ai/valite/api/workflows/support-triage/jobs/replay \
  -H "x-valite-admin-secret: $VALITE_ADMIN_SECRET" \
  -H "x-valite-account-id: <org-id>" -H "Content-Type: application/json" \
  -d '{"models": ["gpt-4o-mini"], "sample": 10, "budget": 5.00}'

Poll and list jobs

GET/valite/api/jobs/{job_id}

Returns the current job object.

GET/valite/api/jobs?workflow={workflow}

Returns {"jobs": [...]}, newest first, scoped to the requesting organization and capped at 500. The workflow filter is optional. With the Postgres control store, job rows survive restarts (jobs still marked running at startup are failed); the dev file store keeps finished jobs in memory (up to 200). Artifacts are the durable record either way.

Job parameters

replay

modelsstring[]required

Candidate models: bare name (gpt-4o-mini), catalog ID (vendor/model), or upstream:model.

sampleinteger

Calls to replay per callsite (default 10, deterministic seeded sampling).

callsitestring

Restrict the replay to a single callsite ID.

budgetnumber (USD)

Spend ceiling. Required unless confirm is true — see budget gating.

confirmboolean

Proceed without a budget ceiling.

bar / validate

knumber

Bar width multiplier: bar = mean − k·σ (default 1.0).

scoresobject

Explicit per-run scores, overriding the workflow's grader or eval command.

ninteger

Cap on baseline runs considered.

forceboolean

Freeze a bar even below the recommended run count (marks it underpowered).

triage

force_includestring[]

Callsite IDs to shortlist regardless of verdict.

force_excludestring[]

Callsite IDs to protect from testing and routing.

plan

strict_compliancenumber

Compliance threshold for schema-strict callsites (default 1.0).

compliancenumber

Compliance threshold for prose callsites (default 0.98).

proxy_floornumber

Minimum quality proxy score (default 0.5).

max_latency_rationumber

Reject candidates slower than this multiple of baseline (0 = no cap).

Budget gating

replay and calibrate spend real provider money. Without a sufficient budget (or confirm: true), the job fails fast — before any spend — and its result carries the projection:

budget-gate failure
{
  "status": "failed",
  "error": "projected cost exceeds budget",
  "result": { "projected_usd": 7.42, "suggested_budget": 11.14 }
}

Tip

Start with the projection: POST with {"budget": 0}, read suggested_budget, then re-run with it.

Result shapes

Each kind's result names its artifact and the headline numbers:

result by kind
profile   {"artifact":"profile","runs":128,"cost_per_run_usd":0.041,"pricing_notes":[...]}
triage    {"artifact":"triage","shortlisted":["cs_9f2ab1","cs_04c77e"]}
bar       {"artifact":"bar","bar":0.87,"mean":0.93,"margin":0.06,"saturated":false,"high_variance":false}
calibrate {"artifact":"calibration","pass":true,"note":""}
replay    {"artifact":"replay","spent_usd":3.12,"candidates":2}
plan      {"artifact":"routing","routes":[...],"notes":[...],"projection":{...},"activation_hint":"..."}
validate  {"artifact":"validation","pass":true,"candidate_cost_per_run_usd":0.0098}
report    {"artifact":"report","report_md":"# Scorecard ..."}

Full artifacts (replay candidate tables, the routing YAML, the rendered report) are read back via the Workflows API.

← Previous

Overview

Next →

Workflows API