curl --request POST \
--url https://ingest.fenra.io/usage/transactions \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"provider": "openai",
"model": "gpt-4o",
"usage": [
{
"type": "tokens",
"metrics": {
"input_tokens": 150,
"output_tokens": 50,
"total_tokens": 200
}
}
],
"context": {
"billable_customer_id": "acme-corp"
}
}
'{
"status": "queued",
"events_queued": 2,
"message": "2 transaction(s) queued for processing",
"results": [
{
"transaction_index": 0,
"message_id": "abc123-def456"
},
{
"transaction_index": 1,
"message_id": "ghi789-jkl012"
}
]
}POST /usage/transactions
Ingest AI usage transactions for cost tracking. Costs are calculated automatically based on the provider’s pricing. Supports both single transaction and bulk submissions. Use this endpoint after each AI provider call to track cost.
curl --request POST \
--url https://ingest.fenra.io/usage/transactions \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"provider": "openai",
"model": "gpt-4o",
"usage": [
{
"type": "tokens",
"metrics": {
"input_tokens": 150,
"output_tokens": 50,
"total_tokens": 200
}
}
],
"context": {
"billable_customer_id": "acme-corp"
}
}
'{
"status": "queued",
"events_queued": 2,
"message": "2 transaction(s) queued for processing",
"results": [
{
"transaction_index": 0,
"message_id": "abc123-def456"
},
{
"transaction_index": 1,
"message_id": "ghi789-jkl012"
}
]
}Request Formats
Single Transaction
{
"provider": "openai",
"model": "gpt-4o",
"usage": [{
"type": "tokens",
"metrics": {
"input_tokens": 100,
"output_tokens": 50,
"total_tokens": 150
}
}],
"context": {
"billable_customer_id": "my-company"
}
}
Bulk Request
{
"transactions": [
{ "provider": "openai", "model": "gpt-4o", ... },
{ "provider": "anthropic", "model": "claude-3-5-sonnet", ... }
]
}
Context
Onlybillable_customer_id is required in the context object. You can add any additional fields. They will be stored and available for filtering in your dashboard.
{
"context": {
"billable_customer_id": "acme-corp"
}
}
Response Codes
| Code | Meaning |
|---|---|
202 Accepted | All transactions queued |
207 Multi-Status | Some succeeded, some failed |
400 Bad Request | Validation error |
401 Unauthorized | Invalid API key |
500 Internal Error | Server error |
Examples
Basic Request
curl -X POST 'https://ingest.fenra.io/usage/transactions' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: YOUR_API_KEY' \
-d '{
"provider": "openai",
"model": "gpt-4o",
"usage": [{
"type": "tokens",
"metrics": {
"input_tokens": 100,
"output_tokens": 50,
"total_tokens": 150
}
}],
"context": {
"billable_customer_id": "my-company"
}
}'
{
"status": "queued",
"events_queued": 1,
"message": "1 transaction(s) queued for processing",
"results": [{
"transaction_index": 0,
"message_id": "abc123-def456-ghi789"
}]
}
Error Responses
Validation Error (400)
{
"error": {
"code": "validation_error",
"message": "Request validation failed",
"details": [
{
"field": "context.billable_customer_id",
"code": "required",
"message": "billable_customer_id is required"
}
]
}
}
Unauthorized (401)
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key"
}
}
Partial Success (207)
{
"status": "partial_success",
"events_queued": 1,
"events_failed": 1,
"message": "1 transaction(s) queued, 1 transaction(s) failed",
"results": [
{
"transaction_index": 0,
"message_id": "abc123"
},
{
"transaction_index": 1,
"message_id": null,
"error": "Validation failed"
}
]
}
See Also
Authorizations
API key for authentication. Must be associated with an active organization.
Body
- Single Transaction
- Bulk Request
Either a single transaction or a bulk request containing multiple transactions
AI provider. Fenra automatically applies the correct pricing for each provider. Use 'custom' for providers not yet supported, combined with custom pricing configuration in your dashboard.
openai, gemini, bedrock, anthropic, xai, deepseek, custom The model identifier (e.g., 'gpt-4o', 'claude-3-opus', 'gemini-pro')
1"gpt-4o"
"claude-3-opus"
"gemini-1.5-pro"
Array of usage entries. Each usage type may appear at most once per transaction.
1- Tokens
- Images
- Audio
- Video
- Requests
- Custom
Show child attributes
Show child attributes
Only billable_customer_id is required. Add any additional fields (environment, feature, user_id, team, etc.) and they will appear in your dashboard for filtering, alerts, and reports.
Show child attributes
Show child attributes
Optional model tier classification for custom pricing tiers
Optional raw usage data from the provider for debugging or auditing
Response
All transactions queued successfully