Skip to main content

​
Create Trace

Send a trace to the Costrace backend. 
POST /v1/traces

​
Headers

Authorization: Bearer ct_your_api_key
Content-Type: application/json

​
Request Body

​
provider
string
required
LLM provider: openai, anthropic, or gemini
​
model
string
required
Model name (e.g., gpt-4o, claude-sonnet-4-20250514)
​
tokens_in
integer
required
Number of input/prompt tokens
​
tokens_out
integer
required
Number of output/completion tokens
​
latency_ms
integer
required
Request latency in milliseconds
​
cost_usd
number
required
Calculated cost in USD
​
api_key
string
required
Your Costrace API key (used to identify the trace source)
​
status
string
required
Request status: success or error
​
error
string
Error message (only if status is error)

​
Example Request

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"
  }'

​
Response

​
status
string
ok if the trace was accepted
{
  "status": "ok"
}
Status Code: 202 Accepted

​
Error Responses

​
400 Bad Request

Invalid request body: 
{
  "error": "Validation error",
  "details": "Missing required field: provider"
}

​
401 Unauthorized

Invalid API key: 
{
  "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)

ProviderModelInput ($/1M)Output ($/1M)
OpenAIgpt-4o$2.50$10.00
OpenAIgpt-4o-mini$0.15$0.60
Anthropicclaude-opus-4-6$5.00$25.00
Anthropicclaude-haiku-4-5$1.00$5.00
Geminigemini-2.0-flash$0.10$0.40
Pricing is subject to change by providers. The SDK includes up-to-date pricing tables.

​
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.