TItiliter
jobs

Finalise a job (kicks off deferred analysis)

Changed on

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

Request

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.

operator_namestring nullable

Display label for the operator who started the job: their name, or their email when no name is set. Set on the job list and on GET /jobs/{id}; omitted elsewhere and when the user row is unavailable.

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.

site_idstring nullable

Site selected at the start of this inspection.

asset_idstring nullable

Asset selected at the start of this inspection.

location_pathstring nullable

Human-readable site and hierarchy path captured when this inspection started.

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.

enforce_live_captureboolean

When True, step photos must be taken with the live camera and library or file uploads are not offered. Mirrors the backing workflow's enforce_live_capture; False when the job has no workflow.

credits_requiredinteger

Workflow credits POST /jobs/{id}/analyse would charge for this job now.

Example response

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

Changes

  • d1aed8b7c278Revision changes
    • info

      added the optional property to the response with the status

  • b83922616927Revision changes
    • warning

      added the new barcode enum value to the // response property for the response status

    • warning

      added the new barcode enum value to the // response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property // to the response with the status