# Authentication
Source: https://docs.costrace.dev/api/authentication

How to authenticate with the Costrace API

## API Keys

All API requests require authentication using your Costrace API key. You can find your API key in the [dashboard](https://costrace.dev/dashboard).

## Header Format

Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer ct_your_api_key_here
```

## Example Request

```bash theme={null}
curl -X POST https://api.costrace.dev/v1/traces \
  -H "Authorization: Bearer ct_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-4o",
    "tokens_in": 100,
    "tokens_out": 50,
    "latency_ms": 1234,
    "cost_usd": 0.005,
    "api_key": "ct_your_api_key",
    "status": "success"
  }'
```

## Key Management

### Getting Your Key

1. Sign up at [costrace.dev/auth](https://costrace.dev/auth)
2. Navigate to your dashboard
3. Copy your API key from the settings or API keys section

### Security Best Practices

<Warning>
  Never commit API keys to version control. Use environment variables instead.
</Warning>

**Good:**

```bash theme={null}
export COSTRACE_API_KEY=ct_your_api_key
```

```python theme={null}
import os
costrace.init(api_key=os.environ["COSTRACE_API_KEY"])
```

**Bad:**

```python theme={null}
# DON'T DO THIS
costrace.init(api_key="ct_abc123...")  # Hardcoded key
```

### Rotating Keys

If your API key is compromised:

1. Generate a new key in the dashboard
2. Update your application environment variables
3. Revoke the old key

## Rate Limits

API keys are subject to rate limits based on your plan:

| Plan | Traces/Month | Rate Limit |
| ---- | ------------ | ---------- |
| Free | 50,000       | 100/min    |
| Pro  | 500,000      | 1,000/min  |

Rate limit headers are included in API responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709136000
```

## Error Responses

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "retry_after": 60
}
```


# Traces API
Source: https://docs.costrace.dev/api/traces

Send and retrieve LLM usage traces

## Create Trace

Send a trace to the Costrace backend.

```http theme={null}
POST /v1/traces
```

### Headers

```
Authorization: Bearer ct_your_api_key
Content-Type: application/json
```

### Request Body

<ParamField type="string">
  LLM provider: `openai`, `anthropic`, or `gemini`
</ParamField>

<ParamField type="string">
  Model name (e.g., `gpt-4o`, `claude-sonnet-4-20250514`)
</ParamField>

<ParamField type="integer">
  Number of input/prompt tokens
</ParamField>

<ParamField type="integer">
  Number of output/completion tokens
</ParamField>

<ParamField type="integer">
  Request latency in milliseconds
</ParamField>

<ParamField type="number">
  Calculated cost in USD
</ParamField>

<ParamField type="string">
  Your Costrace API key (used to identify the trace source)
</ParamField>

<ParamField type="string">
  Request status: `success` or `error`
</ParamField>

<ParamField type="string">
  Error message (only if `status` is `error`)
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.costrace.dev/v1/traces \
    -H "Authorization: Bearer ct_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "openai",
      "model": "gpt-4o",
      "tokens_in": 100,
      "tokens_out": 50,
      "latency_ms": 1234,
      "cost_usd": 0.005,
      "api_key": "ct_your_api_key",
      "status": "success"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.costrace.dev/v1/traces",
      headers={
          "Authorization": "Bearer ct_your_api_key",
          "Content-Type": "application/json",
      },
      json={
          "provider": "openai",
          "model": "gpt-4o",
          "tokens_in": 100,
          "tokens_out": 50,
          "latency_ms": 1234,
          "cost_usd": 0.005,
          "api_key": "ct_your_api_key",
          "status": "success",
      },
  )
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.costrace.dev/v1/traces", {
    method: "POST",
    headers: {
      "Authorization": "Bearer ct_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      provider: "openai",
      model: "gpt-4o",
      tokens_in: 100,
      tokens_out: 50,
      latency_ms: 1234,
      cost_usd: 0.005,
      api_key: "ct_your_api_key",
      status: "success",
    }),
  });
  ```
</CodeGroup>

### Response

<ResponseField name="status" type="string">
  `ok` if the trace was accepted
</ResponseField>

```json theme={null}
{
  "status": "ok"
}
```

**Status Code:** `202 Accepted`

### Error Responses

#### 400 Bad Request

Invalid request body:

```json theme={null}
{
  "error": "Validation error",
  "details": "Missing required field: provider"
}
```

#### 401 Unauthorized

Invalid API key:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

## Cost Calculation

The SDK automatically calculates costs based on current pricing. If you're sending traces manually, use this formula:

```
cost_usd = (tokens_in / 1_000_000) * input_price_per_million +
           (tokens_out / 1_000_000) * output_price_per_million
```

### Example Pricing (as of Feb 2026)

| Provider  | Model            | Input (\$/1M) | Output (\$/1M) |
| --------- | ---------------- | ------------- | -------------- |
| OpenAI    | gpt-4o           | \$2.50        | \$10.00        |
| OpenAI    | gpt-4o-mini      | \$0.15        | \$0.60         |
| Anthropic | claude-opus-4-6  | \$5.00        | \$25.00        |
| Anthropic | claude-haiku-4-5 | \$1.00        | \$5.00         |
| Gemini    | gemini-2.0-flash | \$0.10        | \$0.40         |

<Note>
  Pricing is subject to change by providers. The SDK includes up-to-date pricing tables.
</Note>

## Best Practices

### Use the SDK

The SDKs handle trace creation, cost calculation, and sending automatically. Manual API calls are only needed for:

* Custom integrations
* Non-supported languages
* Debugging

### Fire-and-Forget

Traces are sent asynchronously. Don't wait for responses — they're fire-and-forget by design.

### Error Handling

Failed trace sends should not break your application. The SDK catches network errors silently.


# Introduction
Source: https://docs.costrace.dev/introduction

Track LLM costs, token usage, and latency with one line of code

## What is Costrace?

Costrace is an LLM observability SDK that automatically tracks cost, token usage, and latency for every API call you make to OpenAI, Anthropic, or Google Gemini.

No code changes required, just call `init()` and use your LLM SDKs as normal.

## Key Features

<CardGroup>
  <Card title="Zero Configuration" icon="bolt">
    One line to initialize. Works by monkey-patching your existing LLM client
    libraries.
  </Card>

  <Card title="Real-time Cost Tracking" icon="dollar-sign">
    See exactly how much each API call costs, broken down by model and provider.
  </Card>

  <Card title="Latency Monitoring" icon="gauge">
    Track response times to identify slow endpoints and optimize performance.
  </Card>

  <Card title="Multi-Provider Support" icon="globe">
    OpenAI, Anthropic, and Gemini all tracked automatically.
  </Card>
</CardGroup>

## How It Works

Costrace works by patching the client libraries for OpenAI, Anthropic, and Gemini. When you make an API call, Costrace:

1. Records the start time
2. Lets your call proceed normally
3. Captures token usage and response time
4. Calculates the cost based on current pricing
5. Sends a trace to the Costrace backend (fire-and-forget, non-blocking)

All of this happens transparently! Your code doesn't change.

## Supported Providers

<AccordionGroup>
  <Accordion title="OpenAI">
    All
  </Accordion>

  <Accordion title="Anthropic">All</Accordion>

  <Accordion title="Google Gemini">
    All
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get up and running in 2 minutes
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python">
    Installation and usage for Python
  </Card>

  <Card title="Node.js SDK" icon="node-js" href="/sdks/nodejs">
    Installation and usage for Node.js
  </Card>

  <Card title="API Reference" icon="code" href="/api/traces">
    REST API documentation
  </Card>
</CardGroup>


# Quick Start
Source: https://docs.costrace.dev/quickstart

Get started with Costrace in under 2 minutes

## 1. Get Your API Key

Sign up at [costrace.dev](https://costrace.dev/auth) and grab your API key from the dashboard.

## 2. Install the SDK

<CodeGroup>
  ```bash Python theme={null}
  pip install costrace-sdk[openai]       # OpenAI only
  pip install costrace-sdk[anthropic]    # Anthropic only
  pip install costrace-sdk[gemini]       # Gemini only
  pip install costrace-sdk[all]          # All providers
  ```

  ```bash Node.js theme={null}
  npm install costrace
  ```
</CodeGroup>

## 3. Initialize Costrace

Add one line at the top of your application:

<CodeGroup>
  ```python Python theme={null}
  import costrace

  costrace.init(api_key="ct_your_api_key")
  ```

  ```typescript Node.js theme={null}
  import * as costrace from "costrace";

  costrace.init("ct_your_api_key");
  ```
</CodeGroup>

## 4. Use Your LLM SDKs Normally

That's it. All API calls are now tracked automatically.

<CodeGroup>
  ```python Python theme={null}
  import openai

  client = openai.OpenAI()
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
  )
  ```

  ```typescript Node.js theme={null}
  import OpenAI from "openai";

  const openai = new OpenAI();
  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
  });
  ```
</CodeGroup>

## 5. View Your Traces

Head to [costrace.dev/dashboard/logs](https://costrace.dev/dashboard/logs) to see:

* Cost per call in USD
* Token counts (input/output)
* Latency in milliseconds
* Success/error status
* Geographic distribution

## Local Development

If you're testing locally and want traces to go to your local backend instead of production:

<CodeGroup>
  ```python Python theme={null}
  costrace.init(
      api_key="ct_your_api_key",
      endpoint="http://localhost:8080/v1/traces"
  )
  ```

  ```typescript Node.js theme={null}
  costrace.init(
    "ct_your_api_key",
    "http://localhost:8080/v1/traces"
  );
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Python SDK" icon="python" href="/sdks/python">
    Detailed Python documentation
  </Card>

  <Card title="Node.js SDK" icon="node-js" href="/sdks/nodejs">
    Detailed Node.js documentation
  </Card>
</CardGroup>


# Node.js SDK
Source: https://docs.costrace.dev/sdks/nodejs

Track LLM costs in Node.js and TypeScript applications

## Installation

```bash theme={null}
npm install costrace
```

The SDK has peer dependencies for OpenAI, Anthropic, and Gemini. Only install the ones you use:

```bash theme={null}
npm install openai              # For OpenAI
npm install @anthropic-ai/sdk   # For Anthropic
npm install @google/genai       # For Gemini
```

## Basic Usage

```typescript theme={null}
import * as costrace from "costrace";
import OpenAI from "openai";

// Initialize Costrace once at startup
costrace.init("ct_your_api_key");

// Use OpenAI normally — all calls are tracked
const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});
```

## Configuration

### Custom Endpoint

Point to a self-hosted or local backend:

```typescript theme={null}
costrace.init(
  "ct_your_api_key",
  "https://your-backend.com/v1/traces"
);
```

## Supported Providers

### OpenAI

```typescript theme={null}
import OpenAI from "openai";

const openai = new OpenAI({ apiKey: "sk-..." });
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});
```

**Supported Models:**

* GPT-5 family: `gpt-5.2`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`
* GPT-4 family: `gpt-4o`, `gpt-4o-mini`, `gpt-4.1`, `gpt-4-turbo`, `gpt-4`
* GPT-3.5: `gpt-3.5-turbo`
* Other: `o3`, `o4-mini`

### Anthropic

```typescript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: "sk-ant-..." });
const message = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});
```

**Supported Models:**

* Opus: `claude-opus-4-6`, `claude-opus-4-1-20250805`, `claude-opus-4-20250514`
* Sonnet: `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-sonnet-4-20250514`, `claude-3-7-sonnet-20250219`
* Haiku: `claude-haiku-4-5-20251001`, `claude-3-haiku-20240307`

### Google Gemini

```typescript theme={null}
import { GoogleGenAI } from "@google/genai";

const genai = new GoogleGenAI({ apiKey: "AIza..." });
const response = await genai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: "Hello",
});
```

**Supported Models:**

* Gemini 2.0: `gemini-2.0-flash`, `gemini-2.0-flash-lite`
* Gemini 1.5: `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-1.5-flash-8b`

## What Gets Tracked

Every LLM API call sends a trace containing:

```typescript theme={null}
{
  provider: "openai",           // openai | anthropic | gemini
  model: "gpt-4o",
  tokens_in: 100,               // Prompt tokens
  tokens_out: 50,               // Completion tokens
  latency_ms: 1234,             // Time in milliseconds
  cost_usd: 0.005,              // Calculated cost
  status: "success",            // success | error
  api_key: "ct_...",            // Your Costrace API key
  error: "..."                  // Error message (if status=error)
}
```

Traces are sent using **fire-and-forget fetch** — they don't block your application.

## Manual Cost Calculation

If you need to calculate costs without sending traces:

```typescript theme={null}
import { calculateCost } from "costrace";

const cost = calculateCost("openai", "gpt-4o", 1000, 500);
// Returns cost in USD for 1000 input tokens and 500 output tokens
```

## Requirements

* **Node.js:** 18 or higher (for native `fetch` support)
* **Dependencies:** No runtime dependencies. Provider SDKs are peer dependencies.

## Troubleshooting

### No traces appearing in dashboard

1. Check that `costrace.init()` is called **before** creating LLM clients
2. Verify your API key is correct
3. Check browser console (if client-side) or terminal for error warnings

### TypeScript errors

The SDK is fully typed. If you see type errors, make sure you have the provider SDK installed:

```bash theme={null}
npm install openai @types/node
```

### Traces not being sent

Check your browser console or terminal for `[Costrace]` warnings. The SDK uses `console.warn()` for errors.

## Source Code

GitHub: [github.com/ikotun-dev/costrace](https://github.com/ikotun-dev/costrace)

npm: [npmjs.com/package/costrace](https://www.npmjs.com/package/costrace)


# Python SDK
Source: https://docs.costrace.dev/sdks/python

Track LLM costs in Python applications

## Installation

Install the SDK from PyPI using pip:

```bash theme={null}
pip install costrace-sdk
```

This installs the core SDK with no provider dependencies. To include the provider libraries you need, use extras:

<CodeGroup>
  ```bash OpenAI theme={null}
  pip install costrace-sdk[openai]
  ```

  ```bash Anthropic theme={null}
  pip install costrace-sdk[anthropic]
  ```

  ```bash Google Gemini theme={null}
  pip install costrace-sdk[gemini]
  ```

  ```bash All Providers theme={null}
  pip install costrace-sdk[all]
  ```
</CodeGroup>

If you already have a provider SDK installed (e.g. `openai`, `anthropic`, or `google-genai`), the base `pip install costrace-sdk` is all you need — Costrace will detect and patch any installed providers automatically.

<Note>
  Requires **Python 3.8 or higher**.
</Note>

## How It Works

Costrace uses **monkey-patching** to wrap your existing LLM client methods. When you call `costrace.init()`, it automatically patches the clients for any installed providers — no code changes needed on your end.

Every LLM call is intercepted to capture token usage, latency, and cost, then a trace is sent to the Costrace backend in a **background thread** so your application is never blocked.

## Quick Start

```python theme={null}
import costrace
import openai

# Initialize Costrace once at startup — before creating any LLM clients
costrace.init(api_key="ct_your_api_key")

# Use OpenAI as you normally would — all calls are automatically tracked
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

<Warning>
  You must call `costrace.init()` **before** creating any LLM client instances. The SDK patches client constructors, so clients created before initialization won't be tracked.
</Warning>

## Configuration

### Custom Endpoint

Point to a self-hosted or local backend:

```python theme={null}
costrace.init(
    api_key="ct_your_api_key",
    endpoint="https://your-backend.com/v1/traces"
)
```

## Supported Providers

### OpenAI

```python theme={null}
import costrace
import openai

costrace.init(api_key="ct_your_api_key")

client = openai.OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
```

**Supported Models:**

* GPT-5 family: `gpt-5.2`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`
* GPT-4 family: `gpt-4o`, `gpt-4o-mini`, `gpt-4.1`, `gpt-4-turbo`, `gpt-4`
* GPT-3.5: `gpt-3.5-turbo`
* Other: `o3`, `o4-mini`

### Anthropic

```python theme={null}
import costrace
import anthropic

costrace.init(api_key="ct_your_api_key")

client = anthropic.Anthropic(api_key="sk-ant-...")
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
```

**Supported Models:**

* Opus: `claude-opus-4-6`, `claude-opus-4-1-20250805`, `claude-opus-4-20250514`
* Sonnet: `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-sonnet-4-20250514`, `claude-3-7-sonnet-20250219`
* Haiku: `claude-haiku-4-5-20251001`, `claude-3-haiku-20240307`

### Google Gemini

```python theme={null}
import costrace
from google import genai

costrace.init(api_key="ct_your_api_key")

client = genai.Client(api_key="AIza...")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Hello",
)
```

**Supported Models:**

* Gemini 2.0: `gemini-2.0-flash`, `gemini-2.0-flash-lite`
* Gemini 1.5: `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-1.5-flash-8b`

## What Gets Tracked

Every LLM API call sends a trace containing:

```python theme={null}
{
    "provider": "openai",           # openai | anthropic | gemini
    "model": "gpt-4o",
    "tokens_in": 100,               # Prompt tokens
    "tokens_out": 50,               # Completion tokens
    "latency_ms": 1234,             # Time in milliseconds
    "cost_usd": 0.005,              # Calculated cost
    "status": "success",            # success | error
    "api_key": "ct_...",            # Your Costrace API key
    "error": "..."                  # Error message (if status=error)
}
```

Traces are sent in a **background thread** — they don't block your application. The SDK also registers an `atexit` handler to wait up to 10 seconds for any pending traces before your process exits.

## Requirements

* **Python:** 3.8 or higher
* **Core dependency:** `requests` — installed automatically
* **Provider SDKs:** Optional, install only the ones you use

| Extra       | Installs         | Minimum Version |
| ----------- | ---------------- | --------------- |
| `openai`    | `openai`         | `>=2.21.0`      |
| `anthropic` | `anthropic`      | `>=0.82.0`      |
| `gemini`    | `google-genai`   | `>=1.64.0`      |
| `all`       | All of the above | —               |

## Troubleshooting

### No traces appearing in dashboard

1. Check that `costrace.init()` is called **before** creating LLM clients
2. Verify your API key is correct
3. Check for error messages in console output

### Traces not being sent

The SDK silently catches network errors when sending traces. This is intentional — trace failures should never break your application. Check your network connectivity and ensure the Costrace API endpoint is reachable.

### Provider not being tracked

If a provider isn't being tracked, make sure:

1. The provider SDK is installed (e.g. `pip install openai`)
2. `costrace.init()` is called before creating the client instance
3. You're using a supported model from the lists above

## Source Code

GitHub: [github.com/ikotun-dev/costrace](https://github.com/ikotun-dev/costrace)

PyPI: [pypi.org/project/costrace-sdk](https://pypi.org/project/costrace-sdk)