Under Usage and Requests in the interface, you can see what your applications have used. If you want to bring these figures into your own reporting, your accounting or a dashboard, use the two endpoints GET /usage and GET /usage/requests. A typical case: you pass the costs per customer on to your own customers.
Summary: GET /usage
GET /v1/usage summarizes requests, tokens and costs for a period.
curl "https://api.flowmodels.one/v1/usage?start=2026-10-01&end=2026-10-31&group_by=end_user" \
-H "Authorization: Bearer at_your_key"
startandendare days in the formatYYYY-MM-DD. Without them, you get the last 30 days up to today.group_bydetermines the breakdown:day(default),model,api_keyorend_user.
{
"object": "list",
"data": [
{"bucket": "customer-1042", "requests": 128, "prompt_tokens": 61240, "completion_tokens": 18410, "total_tokens": 79650, "cost_micro_eur": 1840000}
],
"start": "2026-10-01",
"end": "2026-10-31",
"group_by": "end_user"
}
Depending on the grouping, bucket is the day, the model identifier, the key's UUID or your end-user identifier. With group_by=end_user, requests without an end user and requests of deleted end users end up together in one entry with bucket: null. A response contains at most 1,000 entries, so choose shorter periods if you have a lot of end users. cost_micro_eur is the billed amount in micro-euros, so 1,840,000 equals €1.84.
requests counts requests, not individual calls at the provider. A request for which we also summarized history or searched end-user files remains one request. The cost of these additional steps is included in cost_micro_eur, though.
Individual requests: GET /usage/requests
GET /v1/usage/requests lists the individual requests, newest first. Each entry contains:
request_id, created_at, api_key, end_user, model, provider, status, error_code, latency_ms, prompt_tokens, completion_tokens and cost_micro_eur.
provider is the provider at which the request was actually billed. request_id matches the flowai_request_id from the response your application received.
You can filter with these parameters:
status, for examplesuccessapi_keywith a key's UUIDend_userwith your end-user identifier, so the value fromexternal_identifiermodelwith the model identifier as you sent it in the request
Fetch page by page
By default, the list returns 20 entries, and up to 100 with limit. If the response says has_more: true, fetch the next page with after and the value from last_id:
curl "https://api.flowmodels.one/v1/usage/requests?limit=100&end_user=customer-1042&after=aWQ6MTIz" \
-H "Authorization: Bearer at_your_key"
For a complete analysis, repeat this until has_more is false.
Which key you need
Both endpoints work with a key that has the Use AI permission and with a Manage keys key. For a reporting script, we recommend a separate management key that can't call models. Keys from the FlowSuite subscription are rejected here with 403 insufficient_key_scope.
No content
These endpoints never return the text of your requests or the model's responses, not even in part. To clarify an individual call, contact support with the request_id. What data FlowModels stores and for how long explains what we store and for how long.
If something goes wrong
If parameters are wrong, the API responds with 400 invalid_field_value and a clear message, for example:
- "The group_by parameter only accepts day, model, api_key and end_user."
- "The start parameter must be a date in the format YYYY-MM-DD."
- "The start parameter must not be after end."
Prefer to analyze in the interface? Then use Analyze usage and export it as CSV.