Skip to main content
const result = await tracia.prompts.run(slug, variables?, options?);
Execute a prompt with variable substitution and get the generated response. Tracia handles template rendering, LLM API calls, and automatically logs a trace.

​
Parameters

ParameterTypeRequiredDescription
slugstringYesThe prompt slug
variablesRecord<string, string>NoTemplate variables
options.modelstringNoOverride the default model
options.tagsstring[]NoTags for filtering traces
options.userIdstringNoEnd user identifier
options.sessionIdstringNoSession identifier

​
Response

interface RunResult {
  text: string;           // The generated text
  traceId: string;        // Unique trace identifier
  promptVersion: number;  // Version of the prompt used
  latencyMs: number;      // Request latency in milliseconds
  usage: {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
  };
  cost: number;           // Cost in USD
}

​
Examples

​
Basic Usage

const result = await tracia.prompts.run('welcome-email', {
  name: 'Alice',
  product: 'Tracia'
});

console.log(result.text);
// "Dear Alice, Welcome to Tracia!..."

​
With Options

const result = await tracia.prompts.run(
  'welcome-email',
  { name: 'Alice', product: 'Tracia' },
  {
    model: 'gpt-4',
    tags: ['onboarding', 'email'],
    userId: 'user_123',
    sessionId: 'session_abc'
  }
);

​
Accessing Metadata

const result = await tracia.prompts.run('welcome-email', { name: 'Alice' });

console.log(`Latency: ${result.latencyMs}ms`);
console.log(`Tokens: ${result.usage.totalTokens}`);
console.log(`Cost: $${result.cost.toFixed(4)}`);
console.log(`Trace ID: ${result.traceId}`);
console.log(`Prompt Version: ${result.promptVersion}`);

​
Error Handling

import { TraciaError, TraciaErrorCode } from 'tracia';

try {
  const result = await tracia.prompts.run('welcome-email', { name: 'Alice' });
} catch (error) {
  if (error instanceof TraciaError) {
    switch (error.code) {
      case TraciaErrorCode.NOT_FOUND:
        console.error('Prompt does not exist');
        break;
      case TraciaErrorCode.MISSING_VARIABLES:
        console.error('Missing required variables');
        break;
      case TraciaErrorCode.MISSING_PROVIDER_KEY:
        console.error('No LLM provider configured');
        break;
      case TraciaErrorCode.PROVIDER_ERROR:
        console.error('LLM provider error:', error.message);
        break;
    }
  }
}