Request Metadata

Eden AI makes decisions on your behalf on every request: which provider serves a model sold by several, which region it runs in, whether to retry elsewhere when one fails, and whether to use your own provider key. None of that is visible in a normal response, because the answer looks the same whoever produced it. Send the x-edenai-metadata header to have Eden AI attach what it decided.

Enabling it

cURL

curl -X POST https://api.edenai.run/v3/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-edenai-metadata: enabled" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [{"role": "user", "content": "hi"}]
  }'

The value is case-insensitive. Any value other than enabled, including disabled, is treated as off.

The block is absent unless you ask for it, and adding the header changes nothing else: the rest of the response is identical. It is safe to enable per request, for a subset of traffic, or only while debugging.

What you get

The response gains one extra top-level key, edenai_metadata:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [{"...": "..."}],
  "usage": {"...": "..."},
  "edenai_metadata": {
    "requested": "gpt-5.6-sol",
    "strategy": "routed",
    "region": "global",
    "summary": "available=2, served=openai/gpt-5.6-sol",
    "attempt": 1,
    "is_byok": false,
    "endpoints": {
      "total": 2,
      "available": [
        {"provider": "openai", "model": "openai/gpt-5.6-sol", "primary": true, "reachable": true},
        {"provider": "azure", "model": "azure/gpt-5.6-sol", "primary": false, "reachable": true}
      ]
    },
    "attempts": [
      {"provider": "openai", "model": "openai/gpt-5.6-sol", "status": 200, "region": "global"}
    ],
    "tags": {
      "client": "acme",
      "project": "invoices"
    }
  }
}

Field	Meaning
`requested`	The model name you sent, before any resolution
`strategy`	How that name was resolved. See below
`region`	The region the request was served from
`summary`	One-line digest: how many providers were available, and which served
`attempt`	1-based position of the attempt that served. `2` means the first one failed
`is_byok`	Whether your own provider key was used instead of Eden AI’s
`endpoints.total`	How many providers offer the requested model
`endpoints.available`	Each of them, with `primary` (chosen first) and `reachable` (usable for this request)
`attempts`	Every provider actually called, in order, each with its HTTP `status` and `region`
`tags`	The tags recorded for this call, or `{}` when it has none

Strategy values

strategy tells you how much Eden AI chose for you:

Value	Meaning
`direct`	You named a `provider/model`, so no routing happened
`alias`	You named an alias, which resolved to a specific model
`routed`	You named a model without a provider, so Eden AI picked one. See Provider Routing

Reading it on a stream

For streaming requests the block rides the first chunk, not the last. Routing is settled before the first token is generated, so the answer is already known, and putting it first means you get it even from providers that never send a terminal usage chunk.

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion.chunk",
  "choices": [{"delta": {"role": "assistant"}, "index": 0}],
  "edenai_metadata": {"...": "..."}
}

If a stream fails partway through, the error frame carries a corrected block. The retry that happened after the first chunk would otherwise leave you holding a report that says the request succeeded. Read the block from the first chunk, and let a later error frame overwrite it.

What it is useful for

Confirming which provider answered. With provider routing the seller varies per request; summary and attempts name the one that produced your tokens.
Explaining a slow or failed request. attempts records every provider tried with its status, so a retry is visible rather than inferred from latency.
Verifying BYOK. is_byok confirms your own key was used, without reading a bill.
Verifying data residency. region reports where the request was actually served, not merely what you asked for.
Attributing cost. The provider in attempts is the one you were billed for.
Checking your tags. tags shows exactly what was recorded for your usage breakdown, after the key’s default tags, the header and the body are merged.

Scope

Endpoint	Block
`/v3/chat/completions`, `/v3/responses`, `/v3/v1/messages`	Yes, streaming and non-streaming
`/v3/embeddings`, `/v3/moderations`, `/v3/alpha/decisions`	Yes
`/v3/images/generations`, `/v3/images/edits`, `/v3/audio/transcriptions`	Yes
`/v3/videos`	Yes
`/v3/universal-ai`	Yes, synchronous calls, with a shorter block (below)
`POST /v3/universal-ai/async`	Yes, on the 202 job creation response, with a shorter block (below)
`GET /v3/universal-ai/async/{id}`	No
`/v3/audio/speech`	No. The body is raw audio; the `x-edenai-provider` and `x-edenai-cost` response headers name the provider and the cost

The block is also omitted when the response is served from cache, because no provider was called for it.

Universal AI

Universal AI never ranks sellers: you name the provider and, optionally, fallbacks. The block has no strategy or endpoints, and reports mode instead:

"edenai_metadata": {
  "requested": "image/face_compare/facepp",
  "mode": "sync",
  "region": "global",
  "summary": "served=facepp",
  "attempt": 1,
  "is_byok": false,
  "attempts": [
    {"provider": "facepp", "model": "facepp", "status": 200, "region": "global"}
  ],
  "tags": {}
}

Field	Meaning
`mode`	`sync` for synchronous calls, or `async` on the 202 job creation response
`summary`	Which provider served, or `served=none` when every attempt failed

The other fields, including tags, mean the same as above. A failed attempt reports the provider’s own status, even though Universal AI always answers HTTP 200 with "status": "fail".

Next Steps

Provider Routing

How the provider in attempts was chosen

Fallback

Name your own backup models

BYOK

Use your own provider keys

Monitoring

Account-level consumption and credits

V3 Documentation

Quick Start

Overview

LLMs

Expert Models

General

Organization

Data Governance

Integrations

Enabling it

What you get

Strategy values

Tags

Reading it on a stream

What it is useful for

Scope

Universal AI

Next Steps

Provider Routing

Fallback

BYOK

Monitoring

​Enabling it

​What you get

​Strategy values

​Tags

​Reading it on a stream

​What it is useful for

​Scope

​Universal AI

​Next Steps

Provider Routing

Fallback

BYOK

Monitoring

Enabling it

What you get

Strategy values

Tags

Reading it on a stream

What it is useful for

Scope

Universal AI

Next Steps