FAQ

How do I authenticate with Basalt?

To authenticate with Basalt, you’ll need an API key which you can generate from your Basalt dashboard. Then initialize the SDK with your API key:

const basalt = new Basalt({
  apiKey: 'your-api-key'
});

Keep your API key secure and avoid hardcoding it in your application. Use environment variables or a secure secret manager in production environments.

What languages does Basalt SDK support?

How do I manage prompts with Basalt?

Basalt provides a complete prompt management system. You can create and edit prompts in the Basalt web application, then retrieve them in your code using the SDK:

const { value, error } = await basalt.prompt.get('my-prompt-slug');

if (error) {
  console.error('Failed to get prompt:', error);
  return;
}

// Use the prompt with your LLM provider
const response = await yourLLMProvider.complete(value.text);

Prompts can be versioned, tagged, and include variables that you can replace at runtime.

What is the difference between basic monitoring and tracing?

How do experiments work in Basalt?

Experiments allow you to group multiple traces together for comparison. When you create an experiment and attach traces to it, those traces are collected for analysis rather than sent to regular monitoring.This is useful for A/B testing different versions of your workflows, evaluating prompt changes, or optimizing model parameters.

// Create an experiment
const { value: experiment } = await basalt.monitor.createExperiment(
  'feature-slug',
  { name: 'My Experiment' }
);

// Create a trace attached to the experiment
const trace = basalt.monitor.createTrace('feature-slug', {
  experiment: experiment
});

You can then view and analyze the results in the Basalt application.

How does evaluation work in Basalt?

Evaluators are tools that automatically assess the quality of your AI outputs based on specific criteria. You can add evaluators to traces or generations:

const trace = basalt.monitor.createTrace('feature-slug', {
  evaluators: [
    { slug: 'accuracy-evaluator' }
  ]
});

Evaluators are run at sample rates you can configure, except in experiments where they always run at 100% to ensure complete data for comparison. You can create custom evaluators in the Basalt application.

What is the purpose of caching in the SDK?

The SDK includes a built-in caching system with two main components:

API cache: Ensures high availability of prompts even during service disruptions
Local SDK cache: Reduces network requests by storing recently retrieved prompts

By default, caching is enabled with a 5-minute duration. You can disable it for specific requests:

const result = await basalt.prompt.get('welcome-message', {
  cache: false
});

Best practice is to keep caching enabled in production for performance and disable it in development to always get the latest versions.

How do I monitor a complex workflow with multiple steps?

For complex workflows, use Basalt’s tracing system:

Create a main trace for the overall workflow:

const trace = basalt.monitor.createTrace('feature-slug');

Create logs for each major step:

const processingLog = trace.createLog({
  name: 'data-processing',
  type: 'function'
});

Create generations for AI interactions:

const generation = processingLog.createGeneration({
  name: 'summarization',
  prompt: { slug: 'text-summarizer' }
});

End each component when complete:

generation.end(generatedSummary);
processingLog.end();
trace.end(finalResult);

This creates a hierarchical structure that represents your workflow.

How should I handle errors with the SDK?

The Basalt SDK uses a consistent error handling pattern. All methods return an object with value and error properties:

const { value, error } = await basalt.prompt.get('my-prompt');

if (error) {
  // Handle the error appropriately
  console.error('Failed to get prompt:', error.message);
  return;
}

// Value is guaranteed to be defined if no error
const prompt = value;

For traces, make sure to end them even when errors occur:

try {
  // Your workflow code
} catch (error) {
  trace.update({
    metadata: { error: error.message }
  });
  trace.end(`Error: ${error.message}`);
  throw error;
}

How do I associate user information with traces?

You can associate user and organization information with traces for better analytics:

// When creating a trace
const trace = basalt.monitor.createTrace('feature-slug', {
  user: {
    id: 'user-123',
    name: 'John Doe'
  },
  organization: {
    id: 'org-456',
    name: 'Acme Inc'
  }
});

// Or later using the identify method
trace.identify({
  user: {
    id: 'user-123',
    name: 'John Doe'
  }
});

This allows you to filter and analyze traces by user or organization in the Basalt dashboard.

How do I use prompt versions and tags?

Basalt supports versioning and tagging for prompts. You can request specific versions or tags:

// Get a specific version
const { value } = await basalt.prompt.get({
  slug: 'welcome-message',
  version: '1.0.0'
});

// Get a specific tag
const { value } = await basalt.prompt.get({
  slug: 'welcome-message',
  tag: 'production'
});

Versions are immutable and represent specific points in a prompt’s history. Tags are mutable pointers to versions, useful for environment management (e.g., ‘production’, ‘staging’).

How can I improve performance with the SDK?

When will the Datasets feature be available?

Getting Started

Guides

Learn more