Quickstart Guide

Get your first LLM request logged with Helicone in under 2 minutes

This guide will walk you through setting up Helicone and sending your first request. You’ll use our AI Gateway to access 100+ LLM models through the familiar OpenAI SDK with automatic logging built in.

Already using OpenAI, Anthropic, or other providers? Helicone integrates with just a URL change—no refactoring required.

Prerequisites

• A Helicone account (sign up free)
• Node.js or Python installed (or just use cURL)
• 2 minutes

Step 1: Create Your Account

1. Sign up for Helicone

   Navigate to helicone.ai/signup and create your free account.

   Helicone offers a generous free tier with 10,000 requests per month—no credit card required.

2. Generate your API key

   After signing up, go to Settings > API Keys and generate a new API key.

   Save this key securely—you’ll use it to authenticate your requests.

3. Add credits (optional)

   If you want to use Helicone’s AI Gateway to access 100+ models without managing individual provider keys:

   1. Visit helicone.ai/credits
   2. Add credits to your account (starting at $10)
   3. Access any model instantly with 0% markup

   What are credits and how do they work?

   Credits let you access 100+ LLM providers (OpenAI, Anthropic, Google, etc.) without signing up for each one individually. Here’s how it works:

   • 0% markup: You pay exactly what providers charge
   • Unified billing: One account for all providers
   • Instant access: No need to sign up for OpenAI, Anthropic, etc.
   • Automatic fallbacks: Switch providers when one is down
   • Simplified management: We handle provider API keys

   Alternatively, you can bring your own provider keys for direct billing and full control.

Step 2: Send Your First Request

Helicone’s AI Gateway provides an OpenAI-compatible API. Simply point your existing OpenAI SDK to our gateway URL:

TypeScript

import { OpenAI } from "openai";

// Initialize the OpenAI client with Helicone's gateway
const client = new OpenAI({
  baseURL: "https://ai-gateway.helicone.ai",
  apiKey: process.env.HELICONE_API_KEY,
});

// Make a request to any supported model
const response = await client.chat.completions.create({
  model: "gpt-4o-mini", // Try: "claude-sonnet-4", "gemini-2.0-flash"
  messages: [
    { role: "user", content: "Explain Helicone in one sentence." }
  ],
});

console.log(response.choices[0].message.content);

Make sure to set your HELICONE_API_KEY environment variable. Never hardcode API keys in your source code.

Step 3: View Your Request in the Dashboard

Within seconds of sending your request, it will appear in your Helicone dashboard:

1. Navigate to us.helicone.ai/requests
2. You’ll see your request with full details:
   • Request and response bodies
   • Cost breakdown
   • Latency metrics (total time, time to first token)
   • Token usage
   • Model and provider information

Click on any request to see the full conversation, including system prompts, function calls, and streaming details.

Try More Models

One of Helicone’s superpowers is unified access to 100+ models. Try switching models by just changing the model parameter:

Anthropic Claude

const response = await client.chat.completions.create({
  model: "claude-sonnet-4",
  messages: [{ role: "user", content: "Hello!" }],
});

Explore All Models

Browse our catalog of 100+ supported models across 20+ providers

Add Custom Metadata

Enhance your requests with custom properties for better filtering and debugging:

TypeScript

const response = await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Hello!" }],
  },
  {
    headers: {
      "Helicone-Property-User-Id": "user_123",
      "Helicone-Property-Environment": "production",
      "Helicone-Property-Feature": "chatbot",
    },
  }
);

These properties become searchable dimensions in your dashboard, letting you filter requests by user, feature, environment, or any custom tag.

Use custom properties to track costs per user, debug specific features, or analyze performance across environments.

Track Sessions (Multi-Step Workflows)

Building an AI agent or chatbot with multiple LLM calls? Use sessions to group related requests:

TypeScript

import { randomUUID } from "crypto";

const sessionId = randomUUID();

// First request in the session
await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Generate a blog outline" }],
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Name": "Blog Writer",
      "Helicone-Session-Path": "/outline",
    },
  }
);

// Second request in the same session
await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Write the introduction" }],
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Name": "Blog Writer",
      "Helicone-Session-Path": "/introduction",
    },
  }
);

View your session in the Sessions dashboard to see the complete trace tree of your AI workflow.

Learn More About Sessions

Deep dive into session tracking for complex AI agents and workflows

What’s Next?

Now that you’re logging requests, explore what else Helicone can do:

Platform Overview

Understand how Helicone works and explore the architecture

Gateway Features

Set up automatic fallbacks, caching, and rate limits

Cost Tracking

Track costs per user, feature, or any custom dimension

Prompt Management

Deploy and version prompts without code changes

Common Integration Patterns

Using with LangChain

import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  configuration: {
    baseURL: "https://ai-gateway.helicone.ai",
    defaultHeaders: {
      "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,
    },
  },
});

View full LangChain integration guide →

Using with Vercel AI SDK

import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
  baseURL: "https://ai-gateway.helicone.ai",
  apiKey: process.env.HELICONE_API_KEY,
});

View full Vercel AI SDK integration guide →

Async logging (without proxy)

If you prefer not to use a proxy, you can log requests asynchronously:

import { HeliconeManualLogger } from "@helicone/helpers";

const logger = new HeliconeManualLogger({
  apiKey: process.env.HELICONE_API_KEY,
});

await logger.logRequest(requestBody, async (recorder) => {
  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(requestBody),
  });
  
  const data = await response.json();
  recorder.appendResults(data);
  return data;
});

View async logging documentation in our integrations guide

Need Help?

We’re here to support you:

• Join our Discord community for live help
• Email us at [e-mail]
• Browse our documentation for common questions
• Check out example code on GitHub