Monitoring

Learn how to track your Eden AI API consumption and costs with the Management API usage endpoints. The dashboard shows the same data, plus your current credit balance, which is not exposed by the API. Use the endpoints below when you want to pull consumption into your own reporting, alerting or chargeback tooling.

Authentication

Usage endpoints belong to the Management API. They are called with a management key (mgmt-eden-…) that has the manage:read scope, not with an inference key:

Authorization: Bearer <management_key>

Generate a management key from the dashboard (Account → Management Keys) or mint one with an issuer key. Calling these endpoints with an inference key (sk-eden-…) returns 401.

Endpoints

Endpoint	What it returns
`GET /v3/manage/usage/`	The organization’s consumption: a time series per API key, or one total per member with `group_by=user`.
`GET /v3/manage/keys/{key_id}/usage/`	The consumption of one API key as a time series.

Key Concepts

Date window

Parameter	Description
`begin`	First day of the window, inclusive (`YYYY-MM-DD`). Usage before `2026-09-03` is not available through this endpoint (contact support for older data).
`end`	Day after the last day of the window, exclusive (`YYYY-MM-DD`). For example, `begin=2026-10-01&end=2026-11-01` covers all of October 2026.

Provide both or neither. Without them you get the last 7 days. The window may not exceed 366 days.

Batch cost

A chat batch shows as cost on the day it was created. The launch records the reservation and the settlement adds the difference between the final cost and the reservation. The settlement counts as no request and carries no tokens.

Response caching

Responses are cached for 60 seconds per organization and query parameters, so repeated calls within that window return the cached summary.

Step parameter

step is required and controls how the time series is bucketed:

Step Value	Aggregation Period	Use Case
1	Daily	Detailed daily analysis
2	Weekly	Weekly trends
3	Monthly	Monthly reports
4	Yearly	Annual summaries

Filtering Options

Narrow the data with any of these query parameters:

Parameter	Description	Example	Available on
`feature`	Feature category	`text`, `image`, `ocr`	both endpoints
`subfeature`	Specific feature	`chat`, `ocr`, `text_to_speech`	both endpoints
`provider`	AI provider	`openai`, `anthropic`	both endpoints
`phase`	Processing phase, for features that report one		both endpoints
`billing`	Filter traffic by billing mode. `eden` (default) includes only managed-key traffic charged by Eden AI. `own_keys` includes only BYOK traffic (priced but never charged by Eden). `all` includes both.	`eden`	both endpoints
`token`	Only the keys with this name. Use `base_token` for usage not attributed to any key. Ignored when `key_id` is given.	`production-v1`	organization
`key_id`	Only this key, by id. `404` if it is not in the organization.		organization
`user`	Only this member, by email. `404` if they are not in the organization.	`dev@example.com`	organization
`group_by`	`user`: one total per member instead of a time series.	`user`	organization

Monitor Usage

Get the last 7 days of usage, grouped by day, and total it per key:

Python

import requests

headers = {"Authorization": "Bearer YOUR_MANAGEMENT_KEY"}

response = requests.get(
    "https://api.edenai.run/v3/manage/usage/",
    headers=headers,
    params={"step": 1}  # Daily aggregation, last 7 days by default
)
response.raise_for_status()

usage = response.json()["usage"]
print(f"Usage data retrieved for {len(usage)} key(s)")
for entry in usage:
    total = sum(
        feature["total_cost"]
        for day in entry["data"].values()
        for feature in day.values()
    )
    print(f"{entry['token']}: ${total:.2f}")

For a specific period, pass begin and end. Remember that end is exclusive: this returns one monthly bucket covering all of October 2026.

Python

import requests

headers = {"Authorization": "Bearer YOUR_MANAGEMENT_KEY"}

response = requests.get(
    "https://api.edenai.run/v3/manage/usage/",
    headers=headers,
    params={
        "begin": "2026-10-01",
        "end": "2026-11-01",
        "step": 3,  # Monthly aggregation
        "provider": "openai"
    }
)
response.raise_for_status()

for entry in response.json()["usage"]:
    for month, features in entry["data"].items():
        for name, stats in features.items():
            print(f"{entry['token']} | {month} | {name}: {stats['details']} calls, ${stats['total_cost']:.2f}")

Response Format

The organization and per-key endpoints return the same shape: a usage list with one entry per API key, whose data is keyed by period start date, then by feature:

{
  "usage": [
    {
      "token": "production-v1",
      "data": {
        "2026-10-01": {
          "text__chat": {
            "total_cost": 11.30,
            "details": 381,
            "cost_per_provider": {
              "openai": 11.28,
              "anthropic": 0.02
            }
          },
          "image__explicit_content": {
            "total_cost": 0.15,
            "details": 101,
            "cost_per_provider": {
              "google": 0.15
            }
          }
        }
      }
    }
  ]
}

Response Fields

Field	Type	Description
`token`	string	Name of the API key. `base_token` groups usage not attributed to any key.
`data`	object	Period-keyed usage data. Each key is the first day of a bucket (`step`).
`total_cost`	number	Total cost for this feature in this period
`details`	integer	Number of API calls made
`cost_per_provider`	object	Cost breakdown by provider

Feature Naming Convention

Features follow the pattern {category}__{subfeature}:

Key	Description
`text__chat`	LLM chat completions
`text__generation`	Text generation
`text__embeddings`	Text embeddings
`image__explicit_content`	Image moderation
`image__question_answer`	Image Q&A
`ocr__ocr`	OCR text extraction
`audio__text_to_speech`	Text-to-speech

Cost per Member

Add group_by=user to get one total per organization member over the window instead of a time series:

Python

import requests

headers = {"Authorization": "Bearer YOUR_MANAGEMENT_KEY"}

response = requests.get(
    "https://api.edenai.run/v3/manage/usage/",
    headers=headers,
    params={"step": 3, "group_by": "user"}
)
response.raise_for_status()

for member in response.json()["usage"]:
    print(f"{member['user']}: ${member['total_cost']:.2f}")

{
  "usage": [
    {"user": "owner@example.com", "total_cost": 128.40},
    {"user": "dev@example.com", "total_cost": 12.05}
  ]
}

Usage is attributed to a member through the member set on their API keys.

Usage of One Key

GET /v3/manage/keys/{key_id}/usage/ returns the time series of a single key. It takes the same begin, end, step, feature, subfeature, provider and phase parameters. The key_id is the id returned when the key was created or by the key list:

Python

import requests

headers = {"Authorization": "Bearer YOUR_MANAGEMENT_KEY"}

# Find the id of an active key, then fetch its daily usage for the last 7 days
keys = requests.get(
    "https://api.edenai.run/v3/manage/keys/",
    headers=headers,
    params={"limit": 100}
).json()["results"]
active_keys = [k for k in keys if k["id"] and not k["revoked"]]

if not active_keys:
    print("No active key to report on")
else:
    key = active_keys[0]
    response = requests.get(
        f"https://api.edenai.run/v3/manage/keys/{key['id']}/usage/",
        headers=headers,
        params={"step": 1}
    )
    response.raise_for_status()

    usage = response.json()["usage"]
    days = sum(len(entry["data"]) for entry in usage)
    print(f"{key['name']}: usage on {days} day(s) in the last 7 days")

A key that belongs to another organization returns 404.

Checking Your Credit Balance

The account credit balance is not exposed by the Management API. Check it in the Eden AI dashboard, or cap spending per key with a key budget so a runaway integration cannot drain the account.

Error Responses

Status	Cause
`400`	Invalid parameters: `step` missing or outside 1 to 4, only one of `begin`/`end` given, `begin` date earlier than `2026-09-03` (contact support for older data), a window longer than 366 days, or an unknown filter value.
`401`	No management key. An inference key (`sk-eden-…`) cannot call `/v3/manage` endpoints.
`403`	The management key lacks the `manage:read` scope.
`404`	The `key_id` or `user` is not in the management key’s organization.
`503`	The analytics store is temporarily unavailable.

401 with an inference key

{
  "detail": "This endpoint needs a management key. An inference key (sk-eden...) cannot manage an organization; mint a management key from the dashboard and use it here."
}

V3 Documentation

Quick Start

Overview

LLMs

Expert Models

General

Organization

Data Governance

Integrations

Authentication

Endpoints

Key Concepts

Date window

Batch cost

Response caching

Step parameter

Filtering Options

Monitor Usage

Response Format

Response Fields

Feature Naming Convention

Cost per Member

Usage of One Key

Checking Your Credit Balance

Error Responses

​Authentication

​Endpoints

​Key Concepts

​Date window

​Batch cost

​Response caching

​Step parameter

​Filtering Options

​Monitor Usage

​Response Format

​Response Fields

​Feature Naming Convention

​Cost per Member

​Usage of One Key

​Checking Your Credit Balance

​Error Responses

Authentication

Endpoints

Key Concepts

Date window

Batch cost

Response caching

Step parameter

Filtering Options

Monitor Usage

Response Format

Response Fields

Feature Naming Convention

Cost per Member

Usage of One Key

Checking Your Credit Balance

Error Responses