API Reference

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

Base URL

https://ingest.fenra.io

Authentication

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

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

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)

Overview

Endpoints

API Reference

Base URL

Authentication

Authentication Guide

Quick Example

Transaction Schema

Context

Usage

Usage Types

Example: Text Generation (Most Common)

Example: Multimodal (Multiple Resource Types)

Response Codes

Error Reference

Endpoints

POST /usage/transactions

​Base URL

​Authentication

Authentication Guide

​Quick Example

​Transaction Schema

​Context

​Usage

​Usage Types

​Example: Text Generation (Most Common)

​Example: Multimodal (Multiple Resource Types)

​Response Codes

Error Reference

​Endpoints

POST /usage/transactions

Base URL

Authentication

Quick Example

Transaction Schema

Context

Usage

Usage Types

Example: Text Generation (Most Common)

Example: Multimodal (Multiple Resource Types)

Response Codes

Endpoints