TItiliter
jobs

Get a job

Changed on

Return a single job by id, including all step results so far.

Visible to the job's owner, to an ADMIN/OWNER of the organisation that ran the job, or to the assignee of a corrective action linked to this job (either its reinspection job or the original inspection of their assigned finding). Returns 404 for jobs the caller may not see (so existence is not leaked). Steps carrying reference files get short-lived signed URLs minted so the results page can render them without a second round-trip. Signing only runs once the job has reached a terminal status (when the report is shown); the per-second analysing polls skip it. The raw object paths are then dropped so this read carries one reference field, reference_file_urls, and surfaces no blob-storage layout. operator_name says who ran the job.

get/api/v2/jobs/{job_id}

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