The rivano.traces resource gives you programmatic access to every proxied request — its status, cost, token usage, spans, and quality scores.

List traces

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const { data, total } = await rivano.traces.list({
  agentId: 'agent_abc123',
  status: 'error',
  environment: 'production',
  limit: 25,
  offset: 0,
});

console.log(`${total} matching traces`);
for (const trace of data) {
  console.log(trace.id, trace.status, `${trace.durationMs}ms`, `$${trace.costUsd}`);
}

import requests

response = requests.get(
    'https://api.rivano.ai/api/traces',
    headers={'Authorization': 'Bearer rv_...'},
    params={
        'agentId': 'agent_abc123',
        'status': 'error',
        'environment': 'production',
        'limit': 25,
        'offset': 0,
    },
)
result = response.json()
for trace in result['data']:
    print(trace['id'], trace['status'], trace['durationMs'])

curl "https://api.rivano.ai/api/traces?agentId=agent_abc123&status=error&limit=25" \
  -H "Authorization: Bearer rv_..."

TraceFilters parameters

Parameter	Type	Description
`agentId`	`string`	Filter to traces for a specific agent
`status`	`'success' \| 'error'`	Filter by request outcome
`environment`	`string`	Filter by environment: `production`, `staging`, etc.
`sessionId`	`string`	Filter to a specific user session
`startTime`	`string`	ISO 8601 start of time range
`endTime`	`string`	ISO 8601 end of time range
`limit`	`number`	Page size (default: 50, max: 200)
`offset`	`number`	Pagination offset

Get a single trace

Returns full trace detail including all spans and quality scores:

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const trace = await rivano.traces.get('trace_xyz789');

console.log('Status:', trace.status);
console.log('Duration:', trace.durationMs, 'ms');
console.log('Cost:', `$${trace.costUsd}`);
console.log('Tokens:', trace.inputTokens, 'in /', trace.outputTokens, 'out');

for (const span of trace.spans) {
  console.log(`  ${span.name}: ${span.durationMs}ms`);
}

for (const score of trace.scores) {
  console.log(`  Score ${score.name}: ${score.value}`);
}

import requests

response = requests.get(
    'https://api.rivano.ai/api/traces/trace_xyz789',
    headers={'Authorization': 'Bearer rv_...'},
)
trace = response.json()
print('Status:', trace['status'])
for span in trace.get('spans', []):
    print(f"  {span['name']}: {span['durationMs']}ms")

curl https://api.rivano.ai/api/traces/trace_xyz789 \
  -H "Authorization: Bearer rv_..."

Aggregate stats

traces.stats() returns aggregate metrics over a filtered set of traces:

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const stats = await rivano.traces.stats({
  agentId: 'agent_abc123',
  startTime: '2026-01-01T00:00:00Z',
  endTime: '2026-04-01T00:00:00Z',
});

console.log('Total requests:', stats.total);
console.log('Success:', stats.success);
console.log('Error:', stats.error);
console.log('Avg latency:', stats.avgDurationMs, 'ms');
console.log('Total cost:', `$${stats.totalCost}`);
console.log('Total tokens:', stats.totalInputTokens + stats.totalOutputTokens);

import requests

response = requests.get(
    'https://api.rivano.ai/api/traces/stats',
    headers={'Authorization': 'Bearer rv_...'},
    params={
        'agentId': 'agent_abc123',
        'startTime': '2026-01-01T00:00:00Z',
        'endTime': '2026-04-01T00:00:00Z',
    },
)
stats = response.json()
print('Total requests:', stats['total'])
print('Avg latency:', stats['avgDurationMs'], 'ms')

curl "https://api.rivano.ai/api/traces/stats?agentId=agent_abc123&startTime=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer rv_..."

Stats response fields

Field	Type	Description
`total`	`number`	Total matching traces
`success`	`number`	Traces with status `success`
`error`	`number`	Traces with status `error`
`avgDurationMs`	`number`	Average request duration
`totalCost`	`number`	Total estimated cost in USD
`totalInputTokens`	`number`	Sum of input tokens
`totalOutputTokens`	`number`	Sum of output tokens

💡

Combine traces.stats() with date ranges to build cost trend dashboards or SLA reports. For fine-grained cost breakdowns by agent and model, use rivano.costs.breakdown() instead.

Error handling

Error	When it occurs
`SdkAuthError`	Invalid API key
`SdkNotFoundError`	Trace ID does not exist
`SdkError`	Invalid filter parameters

SDK Costs — Cost breakdowns and budget management
SDK Evals — Quality scores and regression detection
CLI Traces — Query traces from the terminal
Core Concepts — Traces — What a trace contains

SDK — Traces