v1

latestOpenAPI 3.1.02026-08-06284092.1 KB

jobs

Finalise a job (kicks off deferred analysis)

Transition IN_PROGRESS -> ANALYSING and fire the analysis worker.

Pre-flight: every workflow step must have at least one captured result (PENDING / RUNNING / COMPLETED / ERRORED - slice 5 adds the "skipped is allowed" relaxation). The credit budget is checked but not yet debited - the worker charges per-step so a failing step refunds cleanly.

Returns immediately with status="analysing"; clients poll GET /{id} to see per-step transitions and the terminal completed / completed_with_errors state.

Re-run path: when the job is already in COMPLETED_WITH_ERRORS, the request reopens analysis for only the ERRORED steps (each is refunded and reset to PENDING) and re-enters the same worker. COMPLETED / ABANDONED / ANALYSING all return 409.

post/api/v2/jobs/{job_id}/analyse

Path parameters

job_idstring required

Response

Successful Response

idstring required

Stable job id.

workflow_idstring required

Id of the workflow this job is running against.

workflow_namestring nullable

Display name of the workflow this job runs against. Null when the workflow row is unavailable. Additive convenience field so clients need not resolve the name from workflow_id separately.

user_idstring required

Id of the user who started the job.

is_adhocboolean

True when this job runs against a synthetic ad-hoc workflow (no predefined steps). Clients render the workflow column as an ad-hoc placeholder rather than the synthetic workflow name.

organization_idstring nullable

Owning organization id. Null for personal jobs.

status'in_progress' | 'analysing' | 'completed' | 'completed_with_errors' | 'abandoned' required

result'pending' | 'passed' | 'failed'

The pass/fail outcome of a job, distinct from its lifecycle status.

Lifecycle (JobLifecycleStatus) answers "did the run finish, and did any step technically error?". Result answers "did the run pass its checks?". The two are independent: a run can finish cleanly (COMPLETED) yet still FAILED because too few steps passed for the workflow's pass policy.

The pass policy is driven by allow_step_failure:

Off: strict. Any errored or failing step makes the result FAILED.
On: threshold. Failures are tolerated until the percentage of evaluable steps that failed exceeds fail_threshold_percent; errored steps count as failures.
PENDING: not yet determined (job still in progress / analysing).
PASSED: the workflow's pass policy is satisfied.
FAILED: the workflow's pass policy is not satisfied.

started_atstring date-time required

When the job was created.

analysing_started_atstring date-time nullable

When the job transitioned to ANALYSING. Null while still IN_PROGRESS. Used by the stale-analysis recovery sweep to time out crashed analysis tasks.

completed_atstring date-time nullable

When the job was completed. Null while in progress.

allow_adhoc_stepboolean

Whether ad-hoc steps may be appended to this job via POST /jobs/{id}/extra-steps. Mirrors the backing workflow's allow_adhoc_step. Clients should gate the add-step UI on this flag rather than fetching the workflow, which is unavailable for hidden ad-hoc workflows.

allow_out_of_order_stepsboolean

When True, steps may be captured in any order. When False, they must be captured in ascending sort_order. Mirrors the backing workflow's allow_out_of_order_steps so clients can gate step selection without fetching the workflow.

allow_step_skipboolean

When True, the job may be finalised (analysed) with steps left uncaptured. When False, every step must be captured first. Mirrors the backing workflow's allow_step_skip so clients can relax the Analyse gate without fetching the workflow.

Example response

{
  "steps": [
    {
      "name": "Overview shot",
      "workflow_note": "Stand back and capture the whole subject in frame.",
      "agent_id": "object-detection-v1"
    }
  ],
  "extra_steps": [
    {
      "agent_id": "object-detection-v1"
    }
  ]
}