GET /api/v1/decision-traces
List decision traces with offset-based pagination. Traces are only recorded when tracing is enabled in tenant settings and the request passes the sample rate check.
Query Parameters
| Parameter | Type | Default | Description |
|---|
customerId | string | — | Filter traces for a specific customer |
requestId | string | — | Filter by request/interaction ID |
limit | integer | 50 | Max results (max 200) |
offset | integer | 0 | Pagination offset |
Response
{
"traces": [
{
"id": "trace_001",
"customerId": "CUST001",
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"decisionFlowKey": "default-flow",
"pipeline": [
{ "stage": "qualification", "candidates": 47, "passed": 32, "durationMs": 12 },
{ "stage": "contact_policy", "candidates": 32, "passed": 28, "durationMs": 8 },
{ "stage": "scoring", "candidates": 28, "durationMs": 15 },
{ "stage": "ranking", "topScore": 0.872, "durationMs": 2 },
{ "stage": "arbitration", "method": "priority_weighted", "durationMs": 3 }
],
"result": {
"count": 5,
"topOffer": { "offerId": "offer_001", "score": 0.872 }
},
"totalDurationMs": 42,
"createdAt": "2026-03-16T14:30:00.000Z"
}
],
"total": 1250,
"limit": 50,
"offset": 0
}
GET /api/v1/decision-traces/
Get a single decision trace with full pipeline detail.
Response
Returns the complete trace object with all pipeline stages, scoring details, and result.
Enabling Decision Traces
Decision traces are controlled by two tenant settings:
| Setting | Description |
|---|
decisionTraceEnabled | Master toggle for trace recording |
decisionTraceSampleRate | Sampling rate (0.0 - 1.0). Set to 1.0 to trace every request |
At high traffic volumes, set the sample rate below 1.0 to avoid excessive storage. A 10% sample rate (0.1) typically provides sufficient forensic coverage.
Roles
| Endpoint | Allowed Roles |
|---|
GET /decision-traces | admin, editor, viewer |
GET /decision-traces/{id} | admin, editor, viewer |
