curl --request GET \
--url https://api.flex.ai/v1/flex/usage/request/{request_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.flex.ai/v1/flex/usage/request/{request_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.flex.ai/v1/flex/usage/request/{request_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.flex.ai/v1/flex/usage/request/{request_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.flex.ai/v1/flex/usage/request/{request_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.flex.ai/v1/flex/usage/request/{request_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.flex.ai/v1/flex/usage/request/{request_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "usage.request",
"currency": "USD",
"request_id": "<string>",
"model": "<string>",
"canonical_model": "<string>",
"status": "<string>",
"prompt_tokens": 123,
"completion_tokens": 123,
"total_tokens": 123,
"total_spend": 123,
"modality": "text",
"billing_unit": "<string>",
"started_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"generated_at": "2023-11-07T05:31:56Z",
"cached_tokens": 123,
"units_consumed": 123
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"code": "<string>",
"doc_url": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"code": "<string>",
"doc_url": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"code": "<string>",
"doc_url": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"code": "<string>",
"doc_url": "<string>"
}
}Usage and cost for a single request
Looks up one request’s usage row for exact per-request cost
attribution — the per-turn complement to the whole-key aggregate
/v1/flex/usage returns.
request_id is the value of the x-litellm-call-id response header
on the original inference call (not the id field in the
response body). Capture that header per call, then join it here.
The lookup is scoped to the calling key: a request made with a
different key returns the same 404 as an id that does not exist.
Rows are written when a request completes, so a lookup immediately
after the call may briefly 404 — retry after a few seconds.
total_spend is the charge applied to your account for this request —
the same figure the /v1/flex/usage aggregates sum, so per-request values
reconcile against those totals exactly. It is not derived from the token
counts returned alongside it: a cached prompt is billed at the lower cached
rate, so a token-based re-derivation reads high.
A request whose billing has not been written yet reports 0.0 rather than
an estimate; billing settles within seconds, so retry if you need the final
figure immediately after the call. Only LiteLLM-routed (text) requests carry
a call id, so rows always have modality=text.
curl --request GET \
--url https://api.flex.ai/v1/flex/usage/request/{request_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.flex.ai/v1/flex/usage/request/{request_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.flex.ai/v1/flex/usage/request/{request_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.flex.ai/v1/flex/usage/request/{request_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.flex.ai/v1/flex/usage/request/{request_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.flex.ai/v1/flex/usage/request/{request_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.flex.ai/v1/flex/usage/request/{request_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "usage.request",
"currency": "USD",
"request_id": "<string>",
"model": "<string>",
"canonical_model": "<string>",
"status": "<string>",
"prompt_tokens": 123,
"completion_tokens": 123,
"total_tokens": 123,
"total_spend": 123,
"modality": "text",
"billing_unit": "<string>",
"started_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"generated_at": "2023-11-07T05:31:56Z",
"cached_tokens": 123,
"units_consumed": 123
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"code": "<string>",
"doc_url": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"code": "<string>",
"doc_url": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"code": "<string>",
"doc_url": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"code": "<string>",
"doc_url": "<string>"
}
}Authorizations
Virtual API key. Create one from the
FlexAI dashboard. Pass as
Authorization: Bearer sk-xxxx.
Path Parameters
The x-litellm-call-id header value from the original response.
Response
Successful response
usage.request USD Raw ledger id — the served routing target; not stable across packaging changes.
Stable catalog id; use this to group and reconcile per-model.
success, failure, or unknown. Failed requests
typically report zero tokens and $0 spend.
text How many of prompt_tokens were served from the prompt cache.
Cached tokens bill at a lower rate, so this is what explains a
total_spend below what prompt_tokens and the published
per-token price would suggest — the two are not meant to agree
on a cache-heavy request.
null means billing has not written this request yet (the same
window in which total_spend is 0.0), which is different from
a request that had no cache hits — that reports 0.
Was this page helpful?