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

# Traces API

> 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 body="provider" type="string" required>
  LLM provider: `openai`, `anthropic`, or `gemini`
</ParamField>

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

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

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

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

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

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

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

<ParamField body="error" 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.