valite
Sign inBook a Demo
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 seven kinds, in pipeline order: profile, goldenset, 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[]

Candidate models: bare name (gpt-4o-mini), catalog ID (vendor/model), or upstream:model. Optional — when omitted, the configured defaults are used (harness.candidates, or the per-workflow harness.workflows.<wf>.candidates override); if neither is set the job fails with a clear error.

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.

goldenset / calibrate / validate

sampleinteger

Sample size: golden items per callsite (default 50), or calls sampled for calibrate/validate (default 20).

ninteger

validate: complete routed runs required before it will judge (defaults to harness.required_runs).

budgetnumber (USD)

calibrate/validate spend provider money — same budget gate as replay.

plan / validate

max_worse_ratenumber

Ceiling on the judged extremely_worse rate (default 0.05).

min_judgedinteger

plan: minimum judged calls before a candidate is routable (default 5).

max_latency_rationumber

plan: reject candidates slower than this multiple of baseline (0 = no cap).

Budget gating

calibrate, replay, and validate 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":[...]}
goldenset {"artifact":"goldenset","callsites":4,"picked":180}
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,"worse_rate":0.02,"spent_usd":0.84}
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