API Reference

Everything you need to integrate with the Fenra API

The Fenra API lets you send AI usage data for cost tracking and analytics.

Base URL

https://api.fenra.io

Authentication

All requests require an API key in the X-Api-Key header:

curl -X POST 'https://api.fenra.io/ingest/usage' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '...'

Get your API key from app.fenra.io under Settings → API Keys.

Authentication Guide

How to get and use API keys.

Quick Example

curl -X POST 'https://api.fenra.io/ingest/usage' \
  -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"
    }
  }'

Response:

{
  "status": "queued",
  "events_queued": 1,
  "message": "1 transaction(s) queued for processing"
}

Transaction Schema

Field	Required	Description
provider	Yes	openai, anthropic, gemini, bedrock, xai, deepseek, or custom
model	Yes	Model identifier (e.g., gpt-4o, claude-3-5-sonnet-20241022)
model_tier	No	Pricing tier (e.g., standard, batch)
usage	Yes	What resources the AI call consumed (tokens, images, audio, etc.). See Usage.
context	Yes	Must include billable_customer_id; can include any additional fields

Context

Only billable_customer_id is required. Add any additional context fields you need. They will appear in your dashboard and can be used for filtering, alerts, and reports.

{
  "context": {
    "billable_customer_id": "acme-corp"
  }
}

See the Transactions Guide for examples of useful context fields.

Usage

The usage field describes what resources an AI call consumed. Different AI operations consume different resources:

• Text generation (GPT, Claude, etc.) consumes tokens
• Image generation (DALL-E, etc.) consumes images
• Speech-to-text/TTS (Whisper, etc.) consumes audio seconds

The usage field is an array because some AI calls consume multiple resource types. For example, a GPT-4 Vision request might consume both tokens (for text) and process images.

Structure of a usage entry:

{
  "type": "tokens",
  "metrics": {
    "input_tokens": 100,
    "output_tokens": 50,
    "total_tokens": 150
  }
}

Each entry has:

• type: The resource type (see table below)
• metrics: The measurements for that resource

Usage Types

Type	Used For	Required Metrics
tokens	Text generation, chat, reasoning	input_tokens, output_tokens, total_tokens
images	Image generation (DALL-E, etc.)	generated
audio_seconds	Speech-to-text, TTS	At least one of input_seconds, output_seconds, total_seconds
video_seconds	Video processing	processed_seconds
requests	Flat per-request pricing	count
custom	Custom billing models	units

Example: Text Generation (Most Common)

{
  "usage": [{
    "type": "tokens",
    "metrics": {
      "input_tokens": 500,
      "output_tokens": 200,
      "total_tokens": 700
    }
  }]
}

Example: Multimodal (Multiple Resource Types)

A request that generates both text and images:

{
  "usage": [
    {
      "type": "tokens",
      "metrics": {
        "input_tokens": 150,
        "output_tokens": 50,
        "total_tokens": 200
      }
    },
    {
      "type": "images",
      "metrics": {
        "generated": 2,
        "size_px": 1024
      }
    }
  ]
}

Each usage type can only appear once per transaction. See the Transactions Guide for detailed information on each usage type and their optional metrics.

Response Codes

Code	Meaning
202 Accepted	Transaction(s) queued successfully
207 Multi-Status	Some transactions queued, some failed
400 Bad Request	Validation error
401 Unauthorized	Invalid API key
500 Internal Error	Server error (retryable)

Error Reference

Complete list of error codes and how to handle them.

Endpoints

POST /ingest/usage

Send one or more AI usage transactions.