Skip to main content
The ZeroEval SDK requires an API key to communicate with the ZeroEval platform. You can obtain your API key from the ZeroEval dashboard.

​
Authentication methods

There are two ways to provide your API key to the SDK: Set the ZEROEVAL_API_KEY environment variable before running your application: 
export ZEROEVAL_API_KEY=your_api_key_here
With this approach, the SDK auto-initializes on the first span: 
import * as ze from "zeroeval";
import { OpenAI } from "openai";

// No need to call ze.init() - it auto-initializes
const openai = ze.wrap(new OpenAI());

const completion = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
});
Auto-initialization happens when the first span is created and ZEROEVAL_API_KEY is present in the environment.

​
Programmatic initialization

Alternatively, you can pass the API key directly when calling ze.init(): 
import * as ze from "zeroeval";

ze.init({ apiKey: "your_api_key_here" });
Never hardcode your API key in source code that will be committed to version control. Use environment variables or a secrets management solution.

​
Configuration options

The init() function accepts several configuration options: 
import * as ze from "zeroeval";

ze.init({
  // Required: Your ZeroEval API key
  apiKey: "your_api_key_here",
  
  // Optional: Custom API URL (defaults to https://api.zeroeval.com)
  apiUrl: "https://api.zeroeval.com",
  
  // Optional: Workspace name (defaults to "Personal Workspace")
  workspaceName: "My Production Workspace",
  
  // Optional: Flush interval in seconds (defaults to 10)
  flushInterval: 5,
  
  // Optional: Maximum spans to buffer before flushing (defaults to 100)
  maxSpans: 200,
  
  // Optional: Collect code details like file paths and line numbers (defaults to true)
  collectCodeDetails: true,
  
  // Optional: Enable/disable specific integrations
  integrations: {
    openai: true,
    vercelai: true,
  },
  
  // Optional: Enable debug logging
  debug: false,
});

​
Configuration details

Your ZeroEval API key. Required unless set via ZEROEVAL_API_KEY environment variable.Type: stringEnvironment variable: ZEROEVAL_API_KEY
The URL of the ZeroEval API endpoint. Only change this if you’re using a self-hosted instance.Type: stringDefault: "https://api.zeroeval.com"Environment variable: ZEROEVAL_API_URL
The name of your workspace. This helps organize traces in the dashboard.Type: stringDefault: "Personal Workspace"Environment variable: ZEROEVAL_WORKSPACE_NAME
How often (in seconds) to flush buffered spans to the API.Type: numberDefault: 10 (seconds)
Maximum number of spans to buffer before forcing a flush.Type: numberDefault: 100
Whether to collect code details like file paths and line numbers for spans.Type: booleanDefault: true
Enable debug logging to see detailed SDK operation logs.Type: booleanDefault: falseEnvironment variable: ZEROEVAL_DEBUG (set to "true")

​
Environment variables reference

Here’s a complete list of environment variables the SDK recognizes:
VariableDescriptionRequired
ZEROEVAL_API_KEYYour ZeroEval API keyYes
ZEROEVAL_API_URLCustom API endpoint URLNo
ZEROEVAL_WORKSPACE_NAMEWorkspace identifierNo
ZEROEVAL_DEBUGEnable debug logging ("true")No

​
Checking initialization status

You can check whether the SDK has been initialized: 
import * as ze from "zeroeval";

ze.init({ apiKey: "your_api_key_here" });

if (ze.isInitialized()) {
  console.log("SDK is ready to use");
}

​
Example: Using .env file

Create a .env file in your project root:
.env
ZEROEVAL_API_KEY=your_api_key_here
ZEROEVAL_WORKSPACE_NAME=Production
ZEROEVAL_DEBUG=false
Load it in your application (using dotenv package): 
import "dotenv/config";
import * as ze from "zeroeval";

// SDK auto-initializes from environment variables
ze.init();

​
Debug mode

When troubleshooting, enable debug mode to see detailed logs: 
import * as ze from "zeroeval";

ze.init({
  apiKey: "your_api_key_here",
  debug: true,
});

// You'll see logs like:
// ZeroEval SDK Configuration:
//   Workspace: Personal Workspace
//   API Key: zer_****key
//   API URL: https://api.zeroeval.com
//   Debug Mode: true
//   Flush Interval: 10s (default)
//   Max Spans: 100 (default)
In debug mode, API keys are automatically masked in logs (e.g., zer_****key) for security.

​
Next steps

Quickstart

Build your first traced application

Manual tracing

Learn how to create custom spans

Build docs developers (and LLMs) love

Get started for freeTalk to us