Skip to main content

Traces / Evidence Spine API

The Trace API provides a delivery trace spine — the chain of delivery attempts and evidence for a single event.

Status: WIRED_SANDBOX. This page describes the current contract surface. It is not a production-live availability claim.

Audience​

Customer / developer investigating delivery history.

What a trace is​

A trace in V1 is a delivery trace spine — the collection of delivery attempts, status transitions, and evidence correlation IDs for a single event. It is built from delivery attempts data and evidence/correlation fields.

This is NOT full distributed tracing. There is no OpenTelemetry integration, no span propagation, and no cross-service trace context in V1.

Endpoint table​

MethodPathDescriptionRead/WriteStatusAuth/scopesIdempotencyOpenAPI
GET/tenants/{tid}/deliveries?event_id={eid}Get delivery trace for an eventReadWIRED_SANDBOXread:deliveriesNot requiredShared (deliveries)
GET/tenants/{tid}/deliveries/{did}Get single delivery attempt detailReadWIRED_SANDBOXread:deliveriesNot requiredShared (deliveries)

Read/write status​

OperationReadWriteStatus
Get delivery trace for an eventYes—WIRED_SANDBOX
Get single delivery attempt detailYes—WIRED_SANDBOX

Traces API is read-only. Traces are built from delivery attempt and evidence data, not directly created by customers.

Get trace example​

curl -sS -H "Authorization: Bearer <api_key>" \
  "https://api.zen-mesh.io/v1/tenants/<tenant_id>/deliveries?event_id=<event_id>"

Response shape​

{
  "deliveries": [
    {
      "id": "del_001",
      "event_id": "evt_abc123",
      "status": "delivered",
      "attempt_number": 1,
      "attempted_at": "2026-07-03T10:30:00Z",
      "response_code": 200,
      "evidence_id": "ev_xyz789"
    },
    {
      "id": "del_002",
      "event_id": "evt_abc123",
      "status": "failed",
      "attempt_number": 2,
      "attempted_at": "2026-07-03T10:31:00Z",
      "response_code": 500,
      "error_message": "upstream timeout",
      "evidence_id": "ev_xyz790"
    }
  ]
}

Error examples​

404 Event not found​

{
  "type": "https://api.zen-mesh.io/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "No deliveries found for event evt_abc123.",
  "instance": "req_abc123"
}

Pagination​

Trace delivery lists support cursor-based pagination. See Pagination and Filtering.

Auth​

Bearer JWT or API key in Authorization header. Tenant-scoped via path parameter. See Authentication for scope model.

OpenAPI coverage​

Not directly covered — uses shared deliveries endpoint. See OpenAPI Spec Index.

UI mapping​

Traffic → Traces

Non-claims​

  • WIRED_SANDBOX: implemented in local/sandbox runtime. Not production-live.
  • Traces are delivery trace spines, not full distributed tracing.
  • Trace completeness depends on evidence/correlation field wiring.
  • Cross-service trace context is not supported in V1.