Traces are the primary observability primitive in Rivano. Every proxied request becomes a trace with full span detail.

GET /api/traces

List traces for the current tenant

Parameters:

Param	Type	Description
`limit`	number	Max results (default 50, max 500)
`offset`	number	Pagination offset
`agentId`	string	Filter by agent ID
`status`	string	`success` or `error`
`environment`	string	Filter by environment tag
`startDate`	string	ISO 8601 start date (inclusive)
`endDate`	string	ISO 8601 end date (inclusive)
`minCostUsd`	number	Minimum cost filter
`maxCostUsd`	number	Maximum cost filter
`minInjectionScore`	number	Minimum injection score (0.0–1.0)

Response (200):

{
  "data": [
    {
      "id": "trace_abc123",
      "agentId": "agent_xyz789",
      "agentName": "customer-support",
      "status": "success",
      "environment": "production",
      "sessionId": "sess_def456",
      "modelProvider": "openai",
      "modelName": "gpt-4o",
      "inputTokens": 842,
      "outputTokens": 214,
      "costUsd": 0.0042,
      "durationMs": 1247,
      "injectionScore": 0.02,
      "piiDetected": [],
      "policiesFired": [],
      "createdAt": "2026-04-04T09:45:00Z"
    }
  ],
  "total": 9841,
  "limit": 50,
  "offset": 0
}

import Rivano from '@rivano/sdk';
const rivano = new Rivano({ apiKey: process.env.RIVANO_API_KEY! });

const traces = await rivano.traces.list({
  agentId: 'agent_xyz789',
  status: 'error',
  startDate: '2026-04-01',
  limit: 100,
});

for (const trace of traces.data) {
  console.log(trace.id, trace.durationMs, 'ms');
}

curl "https://api.rivano.ai/api/traces?agentId=agent_xyz789&status=error&limit=100" \
  -H "Authorization: Bearer rv_api_..."

GET /api/traces/:id

Get full detail for a single trace, including spans

Response (200):

{
  "data": {
    "id": "trace_abc123",
    "agentId": "agent_xyz789",
    "agentName": "customer-support",
    "status": "success",
    "environment": "production",
    "sessionId": "sess_def456",
    "modelProvider": "openai",
    "modelName": "gpt-4o",
    "inputTokens": 842,
    "outputTokens": 214,
    "costUsd": 0.0042,
    "durationMs": 1247,
    "injectionScore": 0.02,
    "piiDetected": [],
    "policiesFired": [],
    "qualityScores": [
      { "scorer": "relevance", "score": 0.87 },
      { "scorer": "coherence", "score": 0.92 }
    ],
    "spans": [
      { "stage": "policy_eval", "durationMs": 8 },
      { "stage": "pii_scan", "durationMs": 3 },
      { "stage": "provider", "durationMs": 1198 },
      { "stage": "quality_score", "durationMs": 12 }
    ],
    "createdAt": "2026-04-04T09:45:00Z"
  }
}

const trace = await rivano.traces.get('trace_abc123');
const providerSpan = trace.data.spans.find(s => s.stage === 'provider');
console.log('Provider latency:', providerSpan?.durationMs, 'ms');

curl https://api.rivano.ai/api/traces/trace_abc123 \
  -H "Authorization: Bearer rv_api_..."

GET /api/traces/stats

Aggregate trace statistics for the tenant

Parameters:

Param	Type	Description
`period`	string	Time window: `1h`, `24h`, `7d`, `30d` (default `24h`)
`agentId`	string	Scope stats to a specific agent
`groupBy`	string	`agent`, `model`, or `environment`

Response (200):

{
  "period": "24h",
  "summary": {
    "totalTraces": 4821,
    "successCount": 4780,
    "errorCount": 41,
    "errorRatePercent": 0.85,
    "totalInputTokens": 4210000,
    "totalOutputTokens": 987000,
    "totalCostUsd": 42.17,
    "avgDurationMs": 1183,
    "p50DurationMs": 987,
    "p95DurationMs": 2841,
    "p99DurationMs": 4120
  },
  "groups": [
    {
      "agentName": "customer-support",
      "traceCount": 3200,
      "totalCostUsd": 28.40,
      "errorRatePercent": 0.6,
      "avgDurationMs": 1050
    },
    {
      "agentName": "invoice-processor",
      "traceCount": 1621,
      "totalCostUsd": 13.77,
      "errorRatePercent": 1.3,
      "avgDurationMs": 1480
    }
  ]
}

const stats = await rivano.traces.stats({
  period: '24h',
  groupBy: 'agent',
});

console.log(`Error rate: ${stats.summary.errorRatePercent}%`);
console.log(`Total cost: $${stats.summary.totalCostUsd}`);

curl "https://api.rivano.ai/api/traces/stats?period=24h&groupBy=agent" \
  -H "Authorization: Bearer rv_api_..."

Agents API — Filter traces by agent
Costs API — Cost breakdown from trace data
Audit Logging — Trace retention and export
SDK Traces — Typed SDK wrapper

Traces API

Related