GET /v1/usage

GET /v1/usage

Returns the current month’s usage for the authenticated customer. Useful for in-app dashboards, alerting, and capacity planning.

This endpoint is itself rate-limited but does not count against your monthly quota.

Request

GET /v1/usage HTTP/1.1
Host: api.oneapi.finance
Authorization: Bearer oa_live_<your_key>

Query parameters

Param	Type	Required	Notes
period	enum	no	current_month (default) | last_month | last_24h.
by	enum	no	key | endpoint. Default: omit, return overall.

Response

{
  "period": "current_month",
  "period_start": "2026-05-01T00:00:00Z",
  "period_end": "2026-06-01T00:00:00Z",
  "plan": "indie",
  "monthly_quota": 100000,
  "monthly_used": 14823,
  "monthly_remaining": 85177,
  "per_minute_quota": 60,
  "by_key": [
    {
      "key_prefix": "oa_live_a1b2c3",
      "name": "production-web",
      "calls": 12500,
      "last_used_at": "2026-05-04T20:15:33Z"
    },
    {
      "key_prefix": "oa_live_d4e5f6",
      "name": "scheduled-jobs",
      "calls": 2323,
      "last_used_at": "2026-05-04T18:00:00Z"
    }
  ],
  "by_endpoint": [
    { "endpoint": "/v1/quote", "calls": 9100, "cache_hit_rate": 0.74 },
    { "endpoint": "/v1/time_series", "calls": 4200, "cache_hit_rate": 0.61 },
    { "endpoint": "/v1/statistics", "calls": 1100, "cache_hit_rate": 0.92 },
    { "endpoint": "/v1/symbol_search", "calls": 423, "cache_hit_rate": 0.0 }
  ]
}

Field reference

Field	Type	Notes
period	string	Echo of the requested period.
period_start	string	ISO 8601 UTC. Inclusive.
period_end	string	ISO 8601 UTC. Exclusive.
plan	string	Current plan: free | indie | pro | business | custom.
monthly_quota	integer	Total calls allowed in this period.
monthly_used	integer	Successful (2xx) calls so far.
monthly_remaining	integer	monthly_quota - monthly_used.
per_minute_quota	integer	Burst limit per key.
by_key	array | null	Present when by=key.
by_endpoint	array | null	Present when by=endpoint.

cache_hit_rate is the fraction of your calls to that endpoint that we served from our internal cache rather than fetching from upstream. A high cache hit rate is good — it means you are paying for calls we did not have to make.

Examples

curl

curl -H "Authorization: Bearer oa_live_..." \
  "https://api.oneapi.finance/v1/usage?by=endpoint"

Python

import httpx, os

r = httpx.get(
    "https://api.oneapi.finance/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['ONEAPI_KEY']}"},
    timeout=10.0,
)
r.raise_for_status()
body = r.json()
pct = body["monthly_used"] / body["monthly_quota"] * 100
print(f"{body['monthly_used']}/{body['monthly_quota']} ({pct:.1f}%) used")

JavaScript

const r = await fetch(
  "https://api.oneapi.finance/v1/usage",
  { headers: { Authorization: `Bearer ${process.env.ONEAPI_KEY}` } },
);
const u = await r.json();
const pct = (u.monthly_used / u.monthly_quota) * 100;
console.log(`${u.monthly_used}/${u.monthly_quota} (${pct.toFixed(1)}%)`);

Errors

Status	code	When
401	unauthenticated	Missing or invalid API key.
429	rate_limit	Burst limit. The minute bucket is the same as for any other endpoint.

See also

• Rate limits — plan caps and burst behavior.
• Authentication — key scopes for /v1/usage.