API Reference

Usage

Every retrieval call is metered. Usage is the basis for billing and quota, and is attributable down to the individual API key.

What we record#

For each call to POST /v1/retrieve, we record one usage event: the customer and API key, a timestamp, the number of chunks returned, the request latency, and a hash of the query. We never store the raw query text.

Which calls count

Any request that reaches retrieval is metered, including zero-result queries — it still consumed search and database work. Requests rejected before retrieval (auth or validation failures) are not billed.

Viewing usage#

Your dashboard shows usage by day, by key, and against your plan limits. For programmatic access, the usage endpoint returns the same data.

GET/v1/usage

Query parameters

fromstring (ISO date)optional

Start of the window, inclusive. Defaults to the start of the current month.

tostring (ISO date)optional

End of the window, exclusive. Defaults to now.

curl

curl "https://api.focusalpha.ai/v1/usage?from=2026-05-01&to=2026-06-01" \
  -H "Authorization: Bearer fa_live_your_key_here"

response.json

{
  "period": { "from": "2026-05-01", "to": "2026-06-01" },
  "totals": { "requests": 1842, "chunksReturned": 14736 },
  "byKey": [
    { "prefix": "fa_live_7Fb3", "requests": 1500 },
    { "prefix": "fa_live_9Kd2", "requests": 342 }
  ]
}

Scope

/v1/usage returns only your own account’s usage — the totals and per-key breakdown for the keys issued to you. The same data is shown in your dashboard.

PreviousDocuments

Next Errors