> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Response

> RunLocalResult fields and token usage

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

## RunLocalResult

| Field          | Type                 | Description                                           |
| -------------- | -------------------- | ----------------------------------------------------- |
| `text`         | `string`             | The generated text response                           |
| `spanId`       | `string`             | Unique span identifier (empty if `sendTrace: false`)  |
| `traceId`      | `string \| null`     | Session identifier if part of multi-turn conversation |
| `latencyMs`    | `number`             | Request latency in milliseconds                       |
| `usage`        | `TokenUsage`         | Token usage breakdown                                 |
| `cost`         | `number \| null`     | Estimated cost in USD (calculated server-side)        |
| `provider`     | `string`             | Provider that handled the request                     |
| `model`        | `string`             | Model used for generation                             |
| `toolCalls`    | `ToolCall[]`         | Tool calls made by the model                          |
| `finishReason` | `FinishReason`       | Why the model stopped generating                      |
| `message`      | `LocalPromptMessage` | Full assistant message for multi-turn conversations   |

### TokenUsage

```typescript theme={null}
interface TokenUsage {
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
}
```

### ToolCall

```typescript theme={null}
interface ToolCall {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
}
```

### FinishReason

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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)}`);
}
```

<Note>
  The `cost` field in the immediate response may be `null`. Accurate cost calculations are available in the Tracia dashboard after span processing.
</Note>

## Usage Patterns

### Logging Metrics

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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}`);
}
```