Get Job

Retrieves a single production job by its unique identifier, enriched with the full list of associated paths and real-time computed progress statistics. This is the primary endpoint for building job detail views, as it aggregates data from three service calls: the job record itself, all paths belonging to the job, and the computed progress across every path and serial number.

Use this endpoint when you need the complete picture of a job — its configuration, its manufacturing routes, and how far along production has progressed. For a lightweight listing without paths or progress, use List Jobs instead.

Request

Path Parameters

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the job to retrieve (e.g. "job_abc123")

Response

200 OK

Returned when the job is found. The response is a single object containing all Job fields plus two additional nested objects: paths and progress.

Job Fields

FieldTypeDescription
idstringUnique identifier for the job
namestringHuman-readable job name, typically a work order number
goalQuantitynumberTarget number of units to produce
jiraTicketKeystring | undefinedJira issue key if linked (e.g. "PI-42")
jiraTicketSummarystring | undefinedSummary text from the linked Jira ticket
jiraPartNumberstring | undefinedPart number from the Jira ticket's custom fields
jiraPrioritystring | undefinedPriority level from Jira (e.g. "High")
jiraEpicLinkstring | undefinedEpic link key from Jira
jiraLabelsstring[] | undefinedLabels from the Jira ticket
createdAtstringISO 8601 timestamp of when the job was created
updatedAtstringISO 8601 timestamp of the last modification

paths — Array of Path objects

Each element in the paths array represents a manufacturing route defined for this job.

FieldTypeDescription
idstringUnique identifier for the path
jobIdstringThe parent job's ID (matches the top-level id)
namestringHuman-readable path name (e.g. "Main Route", "Rework Path")
goalQuantitynumberTarget number of units to produce on this specific path
advancementMode"strict" | "flexible" | "per_step"How serial numbers advance through steps on this path
stepsProcessStep[]Ordered array of process steps in this path (see below)
createdAtstringISO 8601 timestamp of path creation
updatedAtstringISO 8601 timestamp of last path modification

paths[].steps[] — Process Step objects

FieldTypeDescription
idstringUnique identifier for the step
namestringStep name (e.g. "CNC Machining", "QC Inspection")
ordernumberZero-based position of this step in the path sequence
locationstring | undefinedPhysical location or workstation where this step is performed
assignedTostring | undefinedUser ID of the operator assigned to this step
optionalbooleanWhether this step can be skipped without blocking advancement
dependencyType"physical" | "preferred" | "completion_gate"How strictly this step's completion is enforced

progress — Computed JobProgress object

Progress is computed in real time from the current state of all serial numbers across all paths. It is not stored — it is recalculated on every request.

FieldTypeDescription
totalGoalnumberSum of goal quantities across all paths
totalCompletednumberTotal number of serial numbers that have completed all steps
percentCompletenumberOverall completion percentage (totalCompleted / totalGoal * 100)
pathProgressPathProgress[]Per-path breakdown of progress (see below)

progress.pathProgress[] — Per-path progress

FieldTypeDescription
pathIdstringThe path's unique identifier
pathNamestringHuman-readable name of the path
goalnumberGoal quantity for this specific path
completednumberNumber of serial numbers that have completed this path
percentCompletenumberCompletion percentage for this path

400 Bad Request

Returned if a validation error occurs during the request.

ConditionMessage
Malformed or invalid id parameterVaries — describes the specific validation issue

404 Not Found

Returned when no job exists with the given ID.

ConditionMessage
Job does not exist"Job not found: {id}"

500 Internal Server Error

Returned if an unhandled error occurs while fetching the job, paths, or computing progress.

ConditionMessage
Database connection failure"Internal Server Error"
Unexpected runtime exception"Internal Server Error"

Examples

Request

curl -X GET http://localhost:3000/api/jobs/job_abc123 \
  -H "Accept: application/json"

Response

{
  "id": "job_abc123",
  "name": "JOB-2024-001",
  "goalQuantity": 50,
  "jiraTicketKey": "PI-42",
  "jiraTicketSummary": "Build 50 aluminum housings",
  "jiraPartNumber": "ALU-HOUSING-7075",
  "jiraPriority": "High",
  "jiraEpicLink": "PI-10",
  "jiraLabels": ["Q1-2024", "rush"],
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "paths": [
    {
      "id": "path_xyz789",
      "jobId": "job_abc123",
      "name": "Main Route",
      "goalQuantity": 40,
      "advancementMode": "strict",
      "steps": [
        {
          "id": "step_001",
          "name": "CNC Machining",
          "order": 0,
          "location": "Bay 3",
          "assignedTo": "user_op1",
          "optional": false,
          "dependencyType": "physical"
        },
        {
          "id": "step_002",
          "name": "Deburring",
          "order": 1,
          "location": "Bay 3",
          "optional": false,
          "dependencyType": "preferred"
        },
        {
          "id": "step_003",
          "name": "QC Inspection",
          "order": 2,
          "location": "QC Lab",
          "assignedTo": "user_qc1",
          "optional": false,
          "dependencyType": "completion_gate"
        }
      ],
      "createdAt": "2024-01-15T11:00:00.000Z",
      "updatedAt": "2024-01-15T11:00:00.000Z"
    },
    {
      "id": "path_rework01",
      "jobId": "job_abc123",
      "name": "Rework Path",
      "goalQuantity": 10,
      "advancementMode": "flexible",
      "steps": [
        {
          "id": "step_r01",
          "name": "Rework Station",
          "order": 0,
          "location": "Bay 5",
          "optional": false,
          "dependencyType": "physical"
        },
        {
          "id": "step_r02",
          "name": "Re-Inspection",
          "order": 1,
          "location": "QC Lab",
          "optional": false,
          "dependencyType": "completion_gate"
        }
      ],
      "createdAt": "2024-01-16T09:00:00.000Z",
      "updatedAt": "2024-01-16T09:00:00.000Z"
    }
  ],
  "progress": {
    "totalGoal": 50,
    "totalCompleted": 18,
    "percentComplete": 36.0,
    "pathProgress": [
      {
        "pathId": "path_xyz789",
        "pathName": "Main Route",
        "goal": 40,
        "completed": 15,
        "percentComplete": 37.5
      },
      {
        "pathId": "path_rework01",
        "pathName": "Rework Path",
        "goal": 10,
        "completed": 3,
        "percentComplete": 30.0
      }
    ]
  }
}

Notes

  • The progress object is computed on every request — it is not cached or stored. For jobs with many serial numbers, this computation may take slightly longer.
  • If a job has no paths yet, paths will be an empty array [] and progress will reflect zero completion.
  • The steps array within each path is ordered by the order field. Always use order to determine step sequence rather than array index.
  • The assignedTo field on steps contains a user ID, not a display name. Use the Users API to resolve display names if needed.
  • advancementMode controls how serials move through steps: strict requires sequential completion, flexible allows skipping optional steps, and per_step allows per-step override configuration.

Related Endpoints