Skip to main content
GET
/
usage
Read the organization's API usage, grouped by action or day
curl --request GET \
  --url https://api.samsa.ai/public/v1/usage \
  --header 'Authorization: Bearer <token>'
{
  "total_credits": 123,
  "total_requests": 123,
  "buckets": [
    {
      "key": "<string>",
      "credits": 123,
      "requests": 123
    }
  ]
}
Aggregates your organization’s API-attributed credit transactions into usage buckets. Returns total_credits, total_requests, and a list of buckets (key, credits, requests). Narrow the window with from/to, choose the grouping with group_by (by action or by day), and scope to a single key with api_key_id. Requires the usage.read scope.

Authorizations

​
Authorization
string
header
required

Organization API key as a bearer token: Authorization: Bearer samsa_sk_....

Headers

​
authorization
string | null

Query Parameters

​
from
string | null

ISO-8601 date or datetime lower bound (inclusive). Defaults to the current billing period's start when both bounds are omitted.

Example:

"2026-07-01"

​
to
string | null

ISO-8601 date or datetime upper bound (inclusive; a bare date covers the whole day). Defaults to the current billing period's end when both bounds are omitted.

Example:

"2026-07-31"

​
group_by
enum<string>
default:day

Bucket dimension: action (action type) or day (calendar date).

Available options:
action,
day
​
api_key_id
string<uuid> | null

Restrict to one of the organization's API keys (404 if not yours).

Response

Successful Response

GET /usage body — org usage over API-attributed transactions.

​
total_credits
integer
required

Net credits across all buckets.

Example:

45

​
total_requests
integer
required

Billed requests across all buckets.

Example:

9

​
buckets
PublicUsageBucket · object[]
required