const { spans, nextCursor } = await tracia.spans.list(options);
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
options.promptSlug | string | No | Filter by prompt slug |
options.status | 'SUCCESS' | 'ERROR' | No | Filter by status |
options.startDate | Date | No | Filter spans created after this date |
options.endDate | Date | No | Filter spans created before this date |
options.userId | string | No | Filter by end user ID |
options.sessionId | string | No | Filter by session ID |
options.tags | string[] | No | Filter by tags (AND logic) |
options.limit | number | No | Results per page (max 100, default 50) |
options.cursor | string | No | Cursor from previous response |
Response
interface ListSpansResult {
spans: SpanListItem[];
nextCursor?: string;
}
interface SpanListItem {
id: string;
spanId: string;
traceId: string | null;
promptSlug: string | null;
model: string;
status: 'SUCCESS' | 'ERROR';
latencyMs: number;
inputTokens: number;
outputTokens: number;
totalTokens: number;
cost: number | null;
createdAt: string;
}
Examples
Basic Usage
const { spans } = await tracia.spans.list();
console.log(`Found ${spans.length} spans`);
Filtering by Prompt
const { spans } = await tracia.spans.list({
promptSlug: 'welcome-email',
status: 'SUCCESS'
});
spans.forEach(span => {
console.log(`${span.spanId}: ${span.latencyMs}ms, ${span.totalTokens} tokens`);
});
Date Range Filtering
const { spans } = await tracia.spans.list({
startDate: new Date('2024-01-01'),
endDate: new Date('2024-01-31')
});
Filtering by Tags
const { spans } = await tracia.spans.list({
tags: ['production', 'v2'] // Must have ALL tags
});
Pagination
async function getAllSpans() {
const allSpans = [];
let cursor: string | undefined;
do {
const { spans, nextCursor } = await tracia.spans.list({
limit: 100,
cursor
});
allSpans.push(...spans);
cursor = nextCursor;
} while (cursor);
return allSpans;
}
Calculating Costs
const { spans } = await tracia.spans.list({
promptSlug: 'welcome-email',
startDate: new Date('2024-01-01')
});
const totalCost = spans.reduce((sum, s) => sum + (s.cost || 0), 0);
const totalTokens = spans.reduce((sum, s) => sum + s.totalTokens, 0);
console.log(`Total cost: $${totalCost.toFixed(4)}`);
console.log(`Total tokens: ${totalTokens}`);
Error Handling
import { TraciaError, TraciaErrorCode } from 'tracia';
try {
const { spans } = await tracia.spans.list();
} catch (error) {
if (error instanceof TraciaError) {
if (error.code === TraciaErrorCode.UNAUTHORIZED) {
console.error('Invalid API key');
}
}
}