When building AI applications, you often need to track and analyze requests by different dimensions like user ID, feature type, or workflow stage. Custom Properties let you tag LLM requests with metadata, enabling advanced filtering, cost analysis per user or feature, and performance tracking across different parts of your application.
Helicone Custom Properties feature for filtering and segmenting data in the Request table.

Custom Properties appear as headers in the `Request` table.

​
Why use Custom Properties

  • Track unit economics: Calculate cost per user, conversation, or feature to understand your application’s profitability
  • Debug complex workflows: Group related requests in multi-step AI processes for easier troubleshooting
  • Analyze performance by segment: Compare latency and costs across different user types, features, or environments

​
Quick Start

Use headers to add Custom Properties to your LLM requests.
1

Define the Header

Name your header in the format Helicone-Property-[Name] where Name is the name of your custom property.
2

Define the Value

The value is a string that labels your request for this custom property. Here are some examples:
curl https://oai.helicone.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Helicone-Auth: Bearer $HELICONE_API_KEY" \
  -H "Helicone-Property-Conversation: "support_issue_2"" \
  -H "Helicone-Property-App: "mobile"" \
  -H "Helicone-Property-Environment: "production"" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ],
    "max_tokens": 50,
    "temperature": 0.7
  }'

​
Configuration Options

​
Basic Settings

Custom properties use a simple header-based format:
Header FormatTypeDescriptionExample
Helicone-Property-[Name]stringAny custom metadata you want to track"Helicone-Property-Environment": "staging"
Helicone-User-IdstringSpecial property for user tracking (reserved)"Helicone-User-Id": "user-123"

​
Use Cases

Track costs and usage per individual user for billing and optimization:
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://oai.helicone.ai/v1",
  defaultHeaders: {
    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,
  },
});

// Track costs per user for billing
const response = await openai.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: userQuery }]
  },
  {
    headers: {
      "Helicone-Property-Plan": "premium",
      "Helicone-Property-Feature": "chat-completion"
    }
  }
);

// Now you can analyze costs by user, plan type, and feature

​
Understanding Custom Properties

​
How Properties Work

Custom properties are metadata attached to each request that help you: What they enable:
  • Filter requests in the dashboard by any property
  • Calculate costs and metrics grouped by properties
  • Export data segmented by custom dimensions
  • Set up alerts based on property values

​
Updating Properties After Request

You can update properties after a request is made using the REST API: 
// Get the request ID from the response
const { data, response } = await openai.chat.completions
  .create({ /* your request */ })
  .withResponse();

const requestId = response.headers.get("helicone-id");

// Update properties via API
await fetch(`https://api.helicone.ai/v1/request/${requestId}/property`, {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${HELICONE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "Environment": "production",
    "PostProcessed": "true"
  })
});

User Metrics

Track per-user costs and usage with the special Helicone-User-Id property

Sessions

Group related requests with Helicone-Session-Id for workflow tracking

Webhooks

Filter webhook deliveries based on custom property values

Alerts

Set up alerts triggered by specific property combinations