> ## Documentation Index
> Fetch the complete documentation index at: https://polar.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost Events

> Track costs by adding cost metadata to your ingested events

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 icon="square-js" TypeScript (SDK) theme={null}
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",
        },
      },
    },
  ],
});
```

```json cURL theme={null}
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

<Info>
  **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).
</Info>

## Use Cases

### AI/LLM Applications

Track the cost of LLM API calls per customer:

```typescript icon="square-js" TypeScript theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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 icon="square-js" TypeScript theme={null}
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:

```json theme={null}
{
  "_cost": {
    "amount": 0.000125, // $0.00000125
    "currency": "usd"
  }
}
```

### Add Context with Additional Metadata

Combine `_cost` with other metadata to understand cost drivers:

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