Skip to main content
const { spans, nextCursor } = await tracia.spans.list(options);
Retrieve spans with optional filters and cursor-based pagination.

​
Parameters

ParameterTypeRequiredDescription
options.promptSlugstringNoFilter by prompt slug
options.status'SUCCESS' | 'ERROR'NoFilter by status
options.startDateDateNoFilter spans created after this date
options.endDateDateNoFilter spans created before this date
options.userIdstringNoFilter by end user ID
options.sessionIdstringNoFilter by session ID
options.tagsstring[]NoFilter by tags (AND logic)
options.limitnumberNoResults per page (max 100, default 50)
options.cursorstringNoCursor 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');
    }
  }
}