Get Step Statuses

Retrieves the per-step status for every process step in a serial number's path. Each entry shows the step's current status (pending, in_progress, completed, skipped, deferred, or waived), along with step metadata (name, order, optional flag, dependency type) and whether an active override exists.

This is the primary endpoint for building step tracker visualizations, deferred step lists, and completion readiness checks. It provides a complete picture of where a serial stands relative to every step in its manufacturing route.

The response is enriched server-side by joining step status records with the path's step definitions and active override data.

Request

Path Parameters

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the serial number (e.g. "SN-00001")

Response

200 OK

Returned when the request is successful. The response is an array of SnStepStatusView objects, one per step in the serial's path, ordered by step index.

FieldTypeDescription
stepIdstringUnique identifier of the process step
stepNamestringHuman-readable step name (e.g. "CNC Machining")
stepOrdernumberZero-based position of this step in the path sequence
statusstringCurrent status of this step for this serial. One of: "pending", "in_progress", "completed", "skipped", "deferred", "waived"
optionalbooleanWhether this step is configured as optional in the path
dependencyTypestringStep dependency type. One of: "physical", "preferred", "completion_gate"
hasOverridebooleanWhether an active step override exists for this serial at this step

Step Status Values

StatusMeaningHow it's set
pendingStep has not been reached yetInitialized at serial creation for all steps after the first
in_progressSerial is currently at this stepSet when the serial advances to this step, or at creation for step 0
completedStep was completed normallySet when the serial advances past this step, or via complete-deferred
skippedOptional step was bypassedSet during advance-to when an optional/overridden step is bypassed
deferredRequired step was bypassed, must be resolved laterSet during advance-to when a required step is bypassed
waivedDeferred step was formally waivedSet via the waive-step endpoint with approver authorization

400 Bad Request

Returned if the serial ID parameter is missing.

ConditionMessage
Serial ID is missing from the URL"Serial ID is required"

404 Not Found

Returned when the serial does not exist.

ConditionMessage
Serial does not exist"Serial not found"

500 Internal Server Error

Returned if an unhandled error occurs while fetching or enriching step status data.

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

Examples

Request

curl -X GET http://localhost:3000/api/serials/SN-00001/step-statuses \
  -H "Accept: application/json"

Response — Serial mid-path with mixed statuses

[
  {
    "stepId": "step_001",
    "stepName": "CNC Machining",
    "stepOrder": 0,
    "status": "completed",
    "optional": false,
    "dependencyType": "physical",
    "hasOverride": false
  },
  {
    "stepId": "step_002",
    "stepName": "Deburring",
    "stepOrder": 1,
    "status": "skipped",
    "optional": true,
    "dependencyType": "preferred",
    "hasOverride": false
  },
  {
    "stepId": "step_003",
    "stepName": "Heat Treatment",
    "stepOrder": 2,
    "status": "deferred",
    "optional": false,
    "dependencyType": "preferred",
    "hasOverride": false
  },
  {
    "stepId": "step_004",
    "stepName": "Coating",
    "stepOrder": 3,
    "status": "in_progress",
    "optional": false,
    "dependencyType": "physical",
    "hasOverride": false
  },
  {
    "stepId": "step_005",
    "stepName": "Final Inspection",
    "stepOrder": 4,
    "status": "pending",
    "optional": false,
    "dependencyType": "completion_gate",
    "hasOverride": true
  }
]

Response — Newly created serial (all pending except first)

[
  {
    "stepId": "step_001",
    "stepName": "Cutting",
    "stepOrder": 0,
    "status": "in_progress",
    "optional": false,
    "dependencyType": "physical",
    "hasOverride": false
  },
  {
    "stepId": "step_002",
    "stepName": "Welding",
    "stepOrder": 1,
    "status": "pending",
    "optional": false,
    "dependencyType": "preferred",
    "hasOverride": false
  },
  {
    "stepId": "step_003",
    "stepName": "QC Inspection",
    "stepOrder": 2,
    "status": "pending",
    "optional": true,
    "dependencyType": "preferred",
    "hasOverride": false
  }
]

Notes

  • The response is enriched server-side by joining three data sources: SnStepStatus records (for status), the path's ProcessStep definitions (for name, order, optional, dependencyType), and SnStepOverride records (for hasOverride).
  • If the serial's path cannot be found (data inconsistency), the response falls back to raw step status data with empty step names, order 0, optional: false, dependencyType: "preferred", and hasOverride: false.
  • The hasOverride field reflects whether an active override exists. Reversed (deactivated) overrides are not counted.
  • Step statuses are initialized when serials are created via Batch Create Serials. If a serial was created before step status tracking was implemented, it may have no status records.
  • Use the deferred status to build "deferred steps" lists in the UI. Deferred steps can be resolved via Complete Deferred Step or Waive Step.
  • The dependencyType field affects advancement behavior: physical dependencies cannot be skipped (unless optional or overridden), preferred dependencies can be deferred, and completion_gate dependencies block final completion.

Related Endpoints