Skip to main content
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"
  }
}