Cost Events - Polar

Cost Insights works by allowing you to add a special _cost property to any event you ingest through Polar’s Event Ingestion API. These costs are then aggregated and made available through the Metrics API alongside revenue metrics.

The `_cost` Property

Basic Structure

To track costs, add a _cost property to your event’s metadata when ingesting events.

TypeScript (SDK)

import { Polar } from "@polar-sh/sdk";

const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
});

await polar.events.ingest({
  events: [
    {
      name: "llm.inference",
      externalCustomerId: "user_123",
      metadata: {
        _cost: {
          amount: 0.025,
          currency: "usd",
        },
      },
    },
  ],
});

cURL

POST https://api.polar.sh/v1/events/ingest
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "events": [
    {
      "name": "llm.inference",
      "external_customer_id": "user_123",
      "metadata": {
        "_cost": {
          "amount": 0.025,
          "currency": "usd"
        }
      }
    }
  ]
}

Cost Metadata Schema

The _cost property has the following structure:

amount (required): The cost amount in cents as a decimal number
- Example: 0.025 for $0.00025 (a fraction of a cent)
- Example: 150 for $1.50
- Supports up to 17 digits with 12 decimal places for precision
currency (required): The currency code
- Currently only "usd" is supported

Amount must be in cents: The amount field represents the cost in cents, not dollars. For example, 100 = \$1.00, 0.5 = \$0.005 (half a cent), and 0.001 = \$0.00001 (one hundredth of a cent).

Use Cases

AI/LLM Applications

Track the cost of LLM API calls per customer:

TypeScript

import { Polar } from "@polar-sh/sdk";
import OpenAI from "openai";

const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
});

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Make LLM API call
const completion = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello!" }],
});

// Calculate cost (example: $0.03 per 1K input tokens, $0.06 per 1K output tokens)
const inputCost = ((completion.usage.prompt * tokens) / 1000) * 3; // in cents
const outputCost = ((completion.usage.completion * tokens) / 1000) * 6; // in cents
const totalCost = inputCost + outputCost;

// Track the cost in Polar
await polar.events.ingest({
  events: [
    {
      name: "gpt4.completion",
      customerId: "cus_abc123",
      metadata: {
        _cost: {
          amount: totalCost,
          currency: "usd",
        },
        _llm: {
          vendor: "openai",
          model: "gpt-4",
          input_tokens: completion.usage.prompt_tokens,
          output_tokens: completion.usage.completion_tokens,
          total_tokens: completion.usage.total_tokens,
        },
      },
    },
  ],
});

Infrastructure Costs

Track compute, storage, or API costs:

{
  "events": [
    {
      "name": "video.processing",
      "external_customer_id": "user_123",
      "metadata": {
        "_cost": {
          "amount": 45.5, // $0.455
          "currency": "usd"
        },
        "duration_seconds": 120,
        "resolution": "1080p"
      }
    }
  ]
}

Third-Party Service Costs

Track costs from external services:

{
  "events": [
    {
      "name": "email.sent",
      "external_customer_id": "user_123",
      "metadata": {
        "_cost": {
          "amount": 0.0001, // $0.000001
          "currency": "usd"
        },
        "provider": "sendgrid",
        "recipients": 1
      }
    }
  ]
}

Best Practices

Track Costs in Real-Time

Ingest cost events as they occur to maintain accurate, up-to-date metrics:

TypeScript

import { Polar } from "@polar-sh/sdk";

const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
});

// When making an LLM API call
const completion = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello!" }],
});

const cost = calculateCost(completion.usage); // Cost should be in cents

await polar.events.ingest({
  events: [
    {
      name: "llm.completion",
      externalCustomerId: "user_123",
      metadata: {
        _cost: {
          amount: cost,
          currency: "usd",
        },
      },
    },
  ],
});

Use Precise Amounts

The amount field supports up to 12 decimal places, perfect for tracking micro-costs:

{
  "_cost": {
    "amount": 0.000125, // $0.00000125
    "currency": "usd"
  }
}

Add Context with Additional Metadata

Combine _cost with other metadata to understand cost drivers:

{
  "metadata": {
    "_cost": {
      "amount": 0.05, // $0.0005
      "currency": "usd"
    },
    "model": "gpt-4-turbo",
    "tokens": 1000,
    "feature": "chatbot"
  }
}

​The _cost Property

​Basic Structure

​Cost Metadata Schema

​Use Cases

​AI/LLM Applications

​Infrastructure Costs

​Third-Party Service Costs

​Best Practices

​Track Costs in Real-Time

​Use Precise Amounts

​Add Context with Additional Metadata

The `_cost` Property

Basic Structure

Cost Metadata Schema

Use Cases

AI/LLM Applications

Infrastructure Costs

Third-Party Service Costs

Best Practices

Track Costs in Real-Time

Use Precise Amounts

Add Context with Additional Metadata