Skip to main content
GET
Your current monthly usage and tier limits.
A read of where you stand against your tier’s quota for the current calendar month. Does not increment any counter — checking your balance shouldn’t move it.

When to use it

  • Render a dashboard with “X / 250 cold calls used this month”.
  • Detect a runaway script before it hits the per-account 24h circuit breaker.
  • Confirm an overage rate or freshness window without paginating any docs.

Response

Counter semantics

  • total_calls = cached_calls + cold_calls. Both meters count.
  • cold_calls is what bills against your tier’s included monthly budget. When this reaches tier_limits.cold_calls_included, further POST /v1/score calls that would trigger a cold run return 429 cold_budget_exhausted until the next monthly reset.
  • null in tier_limits means unmetered (Enterprise / admin).
  • No overage counter in v1.0. Metered overage is on the v1.5 roadmap; when it ships, an additional counter will appear here for accounts that opt in.

Zero-state

If you haven’t made any calls yet this period (or it’s the first of the month and counters just reset), every counter reads 0 and last_reset reads the current period’s start. There’s no 404 for “never called the API” — we treat that as zero state.

Counter reset

Counters reset on the first of the month at 00:00 UTC. Reset is lazy — the first call after the rollover sets last_reset to the new period start and zeroes the per-period meters. Historical periods are retained 14 months for billing reconciliation but are not exposed via this endpoint.

Why no increment

Stripe’s /v1/subscription doesn’t bill you for reading your subscription state. Same principle. Calling /v1/usage is free — go nuts.

Authorizations

X-API-Key
string
header
required

Live keys are prefixed ki_live_, test keys ki_test_. Issue + revoke keys at https://console.keplerinsights.us. Never embed a key in client-side code — every endpoint is backend-to-API only.

Response

Usage state.

mode
string
user_id
string
period
string
Example:

"2026-05"

tier
string
total_calls
integer
cold_calls
integer
cached_calls
integer
last_reset
string<date-time>
next_reset
string<date-time>
tier_limits
object