Skip to main content
All span operations are available under the tracia.spans namespace. Spans are automatically created when you run prompts or use runLocal(), providing visibility into LLM usage, performance, and costs.
Terminology: A span represents a single LLM call. Multiple spans can be grouped into a trace (session) using the traceId parameter.
import { Tracia, Eval } from 'tracia';

const tracia = new Tracia({ apiKey: process.env.TRACIA_API_KEY });

// List spans with filters
const { spans, nextCursor } = await tracia.spans.list({
  promptSlug: 'welcome-email',
  status: 'SUCCESS',
  limit: 20
});

// Get a single span
const span = await tracia.spans.get('sp_abc123def456');

// Submit an evaluation for a span
await tracia.spans.evaluate('sp_abc123def456', {
  evaluator: 'quality',
  value: Eval.POSITIVE
});

​
Available Methods

List

Get spans with filters and pagination

Get

Retrieve full details of a single span

Evaluate

Submit evaluations for spans

​
Types

​
Span

interface Span {
  id: string;
  spanId: string;
  traceId: string | null;
  parentSpanId: string | null;
  promptSlug: string | null;
  promptVersion: number | null;
  model: string;
  provider: string;
  input: { messages: PromptMessage[] };
  variables: Record<string, string> | null;
  output: string | null;
  status: 'SUCCESS' | 'ERROR';
  error: string | null;
  latencyMs: number;
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  cost: number | null;
  tags: string[];
  userId: string | null;
  sessionId: string | null;
  createdAt: string;
}

​
SpanListItem

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;
}

​
ListSpansOptions

interface ListSpansOptions {
  promptSlug?: string;
  status?: 'SUCCESS' | 'ERROR';
  startDate?: Date;
  endDate?: Date;
  userId?: string;
  sessionId?: string;
  tags?: string[];
  limit?: number;
  cursor?: string;
}

​
EvaluateOptions

interface EvaluateOptions {
  evaluator: string;
  value: number;
  note?: string;
}

​
EvaluateResult

interface EvaluateResult {
  id: string;
  evaluatorKey: string;
  evaluatorName: string;
  value: number;
  source: string;
  note: string | null;
  createdAt: string;
}

​
Eval Constant

Use the Eval constant for binary evaluations: 
import { Eval } from 'tracia';

Eval.POSITIVE  // 1
Eval.NEGATIVE  // 0