Collection Timeline Events

Fetch the chain-of-custody timeline for a collection.

GET /api/collections/{id}/events

Not an SSE stream

Despite the historical name of this page, this endpoint is a plain JSON request, not a Server-Sent Events stream. There is no /api/events/{collectionId} route. To observe live progress, poll this endpoint (or GET /api/collections/{id}). The only SSE stream in the API is connector-generation progress at /api/connectors/generate/{id}/progress.

Authorization

• Customer: Can read events for their own collections (including on-behalf-of collections created for them).
• Analyst / Admin: Can read events for any collection. Test collections (no customer) are analyst-only.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID

Response

Returns the chain-of-custody events for the collection, newest first.

{
  "events": [
    {
      "id": "evt_003",
      "event_type": "analyst_signed_off",
      "actor_name": "John Doe",
      "actor_type": "analyst",
      "timestamp": "2024-01-16T09:00:00Z",
      "new_state": "signed_off",
      "event_data": {
        "analyst_name": "John Doe",
        "checklist": {
          "filesCollected": true,
          "hashesVerified": true,
          "apiLogsReviewed": true,
          "chainComplete": true
        }
      }
    },
    {
      "id": "evt_001",
      "event_type": "collection_created",
      "actor_name": "Jane Smith",
      "actor_type": "customer",
      "timestamp": "2024-01-15T10:30:00Z",
      "new_state": "pending",
      "event_data": {
        "connector_id": "conn_slack001",
        "credential_id": "cred_abc123",
        "priority": "high"
      }
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Event identifier
event_type	string	Chain-of-custody event type (see Event Types)
actor_name	string | null	Resolved actor name (analyst full name, customer contact name, or email); "System" / "Automated Process" for non-user actors
actor_type	string	customer, analyst, system, or automated
timestamp	string	ISO 8601 timestamp
new_state	string | null	Collection state after the event, when applicable
event_data	object | null	Event-specific payload

Example Request

curl -X GET "https://api.traces.io/api/collections/col_abc123/events" \
  -H "Authorization: Bearer <token>"

Polling for Progress

To track an in-flight collection, poll GET /api/collections/{id} (which returns the live status and progress block) and/or this timeline endpoint.

async function pollCollection(id: string) {
  const res = await fetch(`/api/collections/${id}`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  const { status, progress } = await res.json();
  // update UI; repeat on an interval until status is terminal
}

Error Responses

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied"
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Collection not found"
  }
}