Skip to main content
const result = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }]
});

​
RunLocalResult

FieldTypeDescription
textstringThe generated text response
spanIdstringUnique span identifier (empty if sendTrace: false)
traceIdstring | nullSession identifier if part of multi-turn conversation
latencyMsnumberRequest latency in milliseconds
usageTokenUsageToken usage breakdown
costnumber | nullEstimated cost in USD (calculated server-side)
providerstringProvider that handled the request
modelstringModel used for generation
toolCallsToolCall[]Tool calls made by the model
finishReasonFinishReasonWhy the model stopped generating
messageLocalPromptMessageFull assistant message for multi-turn conversations

​
TokenUsage

interface TokenUsage {
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
}

​
ToolCall

interface ToolCall {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
}

​
FinishReason

type FinishReason = 'stop' | 'max_tokens' | 'tool_calls';
  • stop - Model finished naturally
  • max_tokens - Hit the token limit
  • tool_calls - Model wants to call a tool

​
Accessing Response Fields

const result = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is TypeScript?' }
  ],
  tags: ['documentation']
});

// Generated text
console.log(result.text);
// "TypeScript is a strongly typed programming language that builds on JavaScript..."

// Span ID for debugging
console.log(`Span ID: ${result.spanId}`);
// "sp_a1b2c3d4e5f67890"

// Performance metrics
console.log(`Latency: ${result.latencyMs}ms`);
// "Latency: 1234ms"

// Token usage
console.log(`Input tokens: ${result.usage.inputTokens}`);
console.log(`Output tokens: ${result.usage.outputTokens}`);
console.log(`Total tokens: ${result.usage.totalTokens}`);
// "Input tokens: 25"
// "Output tokens: 150"
// "Total tokens: 175"

// Provider info
console.log(`Provider: ${result.provider}`);
console.log(`Model: ${result.model}`);
// "Provider: openai"
// "Model: gpt-4o"

​
Cost Tracking

The cost field contains the estimated cost in USD, calculated server-side when the span is processed: 
const result = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Write a haiku.' }]
});

// Cost is available after span processing
// Check the Tracia dashboard for accurate cost data
if (result.cost !== null) {
  console.log(`Estimated cost: $${result.cost.toFixed(6)}`);
}
The cost field in the immediate response may be null. Accurate cost calculations are available in the Tracia dashboard after span processing.

​
Usage Patterns

​
Logging Metrics

async function runWithLogging(messages: LocalPromptMessage[]) {
  const result = await tracia.runLocal({
    model: 'gpt-4o',
    messages,
    tags: ['monitored']
  });

  console.log(JSON.stringify({
    spanId: result.spanId,
    model: result.model,
    provider: result.provider,
    latencyMs: result.latencyMs,
    inputTokens: result.usage.inputTokens,
    outputTokens: result.usage.outputTokens,
    totalTokens: result.usage.totalTokens
  }));

  return result.text;
}

​
Token Budget Management

const MAX_TOKENS = 10000;
let totalTokensUsed = 0;

async function runWithBudget(messages: LocalPromptMessage[]) {
  if (totalTokensUsed >= MAX_TOKENS) {
    throw new Error('Token budget exceeded');
  }

  const result = await tracia.runLocal({
    model: 'gpt-4o',
    messages,
    maxOutputTokens: Math.min(500, MAX_TOKENS - totalTokensUsed)
  });

  totalTokensUsed += result.usage.totalTokens;
  console.log(`Tokens remaining: ${MAX_TOKENS - totalTokensUsed}`);

  return result;
}

​
Performance Monitoring

const latencies: number[] = [];

async function runWithMonitoring(messages: LocalPromptMessage[]) {
  const result = await tracia.runLocal({
    model: 'gpt-4o',
    messages
  });

  latencies.push(result.latencyMs);

  const avgLatency = latencies.reduce((a, b) => a + b, 0) / latencies.length;
  console.log(`Average latency: ${avgLatency.toFixed(0)}ms`);

  return result;
}

​
TypeScript Types

Import the types for type safety: 
import { Tracia, RunLocalResult, TokenUsage } from 'tracia';

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

async function processResult(): Promise<RunLocalResult> {
  return tracia.runLocal({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello!' }]
  });
}

function logUsage(usage: TokenUsage): void {
  console.log(`Tokens: ${usage.totalTokens}`);
}