> ## Documentation Index > Fetch the complete documentation index at: https://docs.haulstow.co/llms.txt > Use this file to discover all available pages before exploring further. # List delivery events > Returns the public lifecycle timeline ordered by sequence. Prefer webhooks for real-time updates. If polling, fetch the delivery first and refetch events only after its `status` or `updated_at` changes. ## OpenAPI ````yaml /openapi.yaml get /deliveries/{delivery_id}/events openapi: 3.1.0 info: title: HaulStow Developer Delivery API version: 1.0.0 summary: Create, quote, track, and test HaulStow deliveries. description: > The HaulStow Developer Delivery API is a server-to-server API for existing HaulStow business customers. Authenticate every request with a business-bound `hsg_live_key_...` API key. Use a test key with the sandbox base URL for deterministic, side-effect-free integration testing. All JSON responses use the same envelope. Every response includes `X-Request-ID` and rate-limit headers. Keep the request ID when contacting HaulStow support. contact: name: HaulStow Developer Support email: support@haulstow.co servers: - url: https://developer.haulstow.co/v1 description: Live security: - DeveloperApiKey: [] tags: - name: Quotes description: Calculate a delivery quote without creating a delivery. - name: Recipients description: Manage business-scoped recipients and reusable addresses. - name: Deliveries description: Create and inspect deliveries created by the authenticated application. - name: Sandbox description: Test-only helpers that never affect live operations. - name: Webhooks description: Signed delivery lifecycle callbacks sent by HaulStow. paths: /deliveries/{delivery_id}/events: get: tags: - Deliveries summary: List delivery events description: | Returns the public lifecycle timeline ordered by sequence. Prefer webhooks for real-time updates. If polling, fetch the delivery first and refetch events only after its `status` or `updated_at` changes. operationId: listDeliveryEvents parameters: - $ref: '#/components/parameters/XRequestID' - $ref: '#/components/parameters/DeliveryID' responses: '200': description: Events returned. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/EventListSuccessResponse' example: success: true statusCode: 200 message: OK data: - id: evt_0c2d2dcbd51a4fa6aa7e566e0e2b2458 type: delivery.created status: booked sequence: 1 occurred_at: '2026-08-20T14:20:00Z' - id: evt_47351d65d53840ce8f4ff7d6d83f1be9 type: delivery.assigned status: assigned sequence: 2 occurred_at: '2026-08-20T14:21:30Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/DeliveryNotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: XRequestID: name: X-Request-ID in: header required: false description: > Optional caller correlation ID. Use 1–128 ASCII letters, digits, `.`, `_`, `-`, or `:`. Invalid values are replaced. The accepted/generated value is returned in the response. schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._:-]+$ example: req_shop_1842_create DeliveryID: name: delivery_id in: path required: true schema: $ref: '#/components/schemas/DeliveryID' headers: XRequestID: description: Correlation ID for the request. schema: type: string example: 01J5T33T75A8S2JCB37Y6Z5Y4N RateLimitLimit: description: Maximum requests available in the current window. schema: type: integer minimum: 0 example: 120 RateLimitRemaining: description: Requests remaining in the current window. schema: type: integer minimum: 0 example: 119 RateLimitReset: description: Unix timestamp in seconds when the current window resets. schema: type: integer format: int64 example: 1787236260 RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 1 example: 30 schemas: EventListSuccessResponse: $ref: '#/components/schemas/SuccessEnvelopeEventList' DeliveryID: type: string pattern: ^dlv_[a-f0-9]{32}$ example: dlv_3f1a821cdb58498cbb52f4706545a089 SuccessEnvelopeEventList: type: object additionalProperties: false required: - success - statusCode - message - data properties: success: type: boolean const: true statusCode: type: integer enum: - 200 message: type: string data: type: array items: $ref: '#/components/schemas/DeliveryEvent' ErrorResponse: type: object additionalProperties: false required: - success - statusCode - message - error properties: success: type: boolean const: false statusCode: type: integer minimum: 400 maximum: 599 message: type: string error: $ref: '#/components/schemas/ErrorPayload' DeliveryEvent: type: object additionalProperties: false required: - id - type - status - sequence - occurred_at properties: id: $ref: '#/components/schemas/EventID' type: $ref: '#/components/schemas/DeliveryEventType' status: $ref: '#/components/schemas/DeliveryStatus' sequence: type: integer minimum: 1 occurred_at: type: string format: date-time ErrorPayload: type: object additionalProperties: false required: - code properties: code: type: string description: Stable machine-readable error code. example: VALIDATION_ERROR details: type: object additionalProperties: true description: >- Optional structured context. Do not parse `message` for control flow. EventID: type: string pattern: ^evt_[a-f0-9]{32}$ example: evt_47351d65d53840ce8f4ff7d6d83f1be9 DeliveryEventType: type: string enum: - delivery.created - delivery.assigned - delivery.picked_up - delivery.in_transit - delivery.delivered - delivery.failed - delivery.cancelled - delivery.outsourced - webhook.test DeliveryStatus: type: string enum: - booked - assigned - picked_up - in_transit - delivered - failed - cancelled - outsourced example: in_transit responses: Unauthorized: description: >- API key is missing, malformed, revoked, expired, or belongs to another environment. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid: value: success: false statusCode: 401 message: API key is invalid error: code: INVALID_API_KEY revoked: value: success: false statusCode: 401 message: API key has been revoked error: code: API_KEY_REVOKED expired: value: success: false statusCode: 401 message: API key has expired error: code: API_KEY_EXPIRED environment: value: success: false statusCode: 401 message: API key does not match this environment error: code: ENVIRONMENT_MISMATCH Forbidden: description: The authenticated key lacks the operation's required scope. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false statusCode: 403 message: API key lacks the required scope error: code: INSUFFICIENT_SCOPE details: required_scope: deliveries:write DeliveryNotFound: description: Delivery was not found for the authenticated application. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false statusCode: 404 message: Delivery not found error: code: DELIVERY_NOT_FOUND RateLimited: description: Rate limit exceeded. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false statusCode: 429 message: Too many requests; please try again later error: code: RATE_LIMIT_EXCEEDED InternalError: description: Unexpected server error. Quote `X-Request-ID` when contacting support. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false statusCode: 500 message: Internal server error error: code: INTERNAL_SERVER_ERROR securitySchemes: DeveloperApiKey: type: http scheme: bearer bearerFormat: hsg_live_key_... or hsg_test_key_... description: > A business-bound HaulStow API key. Send `Authorization: Bearer hsg_live_key_...` to the live server or a `hsg_test_key_...` key to the sandbox server. Never expose this key in a browser. ````