FlowModels

Analyze usage via API: GET /usage and GET /usage/requests

Published on 11. November 2026

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"
  • start and end are days in the format YYYY-MM-DD. Without them, you get the last 30 days up to today.
  • group_by determines the breakdown: day (default), model, api_key or end_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 example success
  • api_key with a key's UUID
  • end_user with your end-user identifier, so the value from external_identifier
  • model with 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.

Was this article helpful?

Back to Usage & logs