List Audit Entries

Retrieves audit trail entries with optional pagination. Returns entries in reverse chronological order (newest first). Each entry represents a single production event with full context — the action type, the user who performed it, when it happened, and references to the affected domain objects.

Use this endpoint to build audit trail dashboards, generate compliance reports, or investigate production events. For serial-specific audit trails, use the Get Audit by Serial endpoint instead.

Request

Query Parameters

ParameterTypeRequiredDescription
limitnumberNoMaximum number of entries to return. If omitted, returns all entries.
offsetnumberNoNumber of entries to skip before returning results. Use with limit for pagination.

Response

200 OK

Returns an array of AuditEntry objects. If no entries exist (or the offset exceeds the total count), returns an empty array [].

FieldTypeDescription
idstringUnique identifier for the audit entry (prefixed with aud_)
actionAuditActionThe type of event (see Action Types)
userIdstringThe user who performed the action
timestampstringISO 8601 timestamp of when the event occurred
serialIdstring | undefinedThe serial number involved, if applicable
certIdstring | undefinedThe certificate involved, if applicable
jobIdstring | undefinedThe job involved, if applicable
pathIdstring | undefinedThe path involved, if applicable
stepIdstring | undefinedThe process step involved, if applicable
fromStepIdstring | undefinedThe step the serial moved from (for serial_advanced events)
toStepIdstring | undefinedThe step the serial moved to (for serial_advanced events)
batchQuantitynumber | undefinedThe number of serials in a batch (for serial_created events)
metadataRecord<string, unknown> | undefinedAction-specific data (e.g., scrap reason, BOM change description)

500 Internal Server Error

Returned if an unhandled error occurs while querying the database.

ConditionMessage
Database read failure"Internal Server Error"

Examples

Request — All entries

curl http://localhost:3000/api/audit

Request — Paginated (first 20 entries)

curl "http://localhost:3000/api/audit?limit=20&offset=0"

Request — Second page

curl "http://localhost:3000/api/audit?limit=20&offset=20"

Response — Mixed audit entries

[
  {
    "id": "aud_001",
    "action": "serial_advanced",
    "userId": "user_abc",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "serialId": "sn_xyz",
    "jobId": "job_abc123",
    "pathId": "path_xyz",
    "fromStepId": "step_001",
    "toStepId": "step_002"
  },
  {
    "id": "aud_002",
    "action": "cert_attached",
    "userId": "user_abc",
    "timestamp": "2024-01-15T10:25:00.000Z",
    "serialId": "sn_xyz",
    "certId": "cert_abc123",
    "stepId": "step_001",
    "jobId": "job_abc123",
    "pathId": "path_xyz"
  },
  {
    "id": "aud_003",
    "action": "serial_created",
    "userId": "user_def",
    "timestamp": "2024-01-15T10:00:00.000Z",
    "jobId": "job_abc123",
    "pathId": "path_xyz",
    "batchQuantity": 10
  },
  {
    "id": "aud_004",
    "action": "serial_scrapped",
    "userId": "user_abc",
    "timestamp": "2024-01-15T09:45:00.000Z",
    "serialId": "sn_bad",
    "jobId": "job_abc123",
    "pathId": "path_xyz",
    "stepId": "step_002",
    "metadata": {
      "reason": "out_of_tolerance",
      "explanation": "Diameter measured 0.003 over spec"
    }
  },
  {
    "id": "aud_005",
    "action": "bom_edited",
    "userId": "user_xyz",
    "timestamp": "2024-01-14T16:00:00.000Z",
    "metadata": {
      "bomId": "bom_abc123",
      "changeDescription": "Increased bolt quantity per engineering review",
      "versionNumber": 2
    }
  }
]

Response — No entries

[]

Notes

  • The audit trail is read-only. There are no endpoints to create, update, or delete audit entries. Entries are generated automatically by the service layer as side effects of production operations.
  • The limit and offset parameters are parsed from query strings and converted to numbers. Non-numeric values are ignored (treated as if not provided).
  • When neither limit nor offset is provided, the endpoint returns all audit entries. For large production environments, always use pagination to avoid oversized responses.
  • The fields present on each entry depend on the action type. For example, fromStepId and toStepId are only present on serial_advanced entries, while batchQuantity is only present on serial_created entries.
  • The metadata field contains action-specific data. For serial_scrapped events, it includes reason and optionally explanation. For bom_edited events, it includes bomId, changeDescription, and versionNumber. For step_waived events, it includes reason and approverId.
  • Client-side filtering by action, userId, serialId, jobId, or date range is recommended for building filtered views. The API does not currently support server-side filtering beyond pagination.

Related Endpoints