Check Your Usage

There are two ways to see how much of your plan is left, and they always agree:

• The headers on every answer. Each call made with your key reports the calls left this month and this minute.
• GET /v1/keys/me/usage. One call that returns the same numbers as JSON, plus your plan.

The limits belong to your account, not to one key: every key on the account draws from the same monthly and per-minute limits.

Response headers

Every answer to a call made with a valid key carries these headers. That includes answers served from the cache, rejected calls (4xx) and rate-limit refusals (429).

Header	Value
X-RateLimit-Limit	Your monthly call limit.
X-RateLimit-Remaining	Calls left this month.
X-RateLimit-Reset	When the monthly count starts again, as Unix time in seconds: 00:00 UTC on the 1st of next month.
X-RateLimit-Burst-Limit	Calls a minute your plan allows.
X-RateLimit-Burst-Remaining	Calls left in the current minute. Minutes are UTC clock minutes.
X-RateLimit-Plan	Your plan: sandbox, builder, launch or scale.
Retry-After	On a per-minute 429 only: seconds until the current minute ends.

Only successful (2xx) answers use the monthly count, so a rejected call leaves X-RateLimit-Remaining unchanged. Every call made in a minute, rejected ones included, uses the per-minute count.

A header is left out when its count was not read for that call, rather than guessed. For example, a call refused by the per-address limit has no X-RateLimit-Remaining.

Endpoint

GET /v1/keys/me/usage

This call is not billed and does not use your plan's limits, so it still answers while your plan is refusing calls. Each key may make it 60 times a minute, shared with GET /v1/keys/me. Past that it returns 429 burst_limit_exceeded with Retry-After set to the seconds left in the minute.

Example request

curl

curl "https://api.asterwise.com/v1/keys/me/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

response = requests.get(
    "https://api.asterwise.com/v1/keys/me/usage",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=10,
)
usage = response.json()["data"]
print(f"{usage['calls_remaining']} of {usage['calls_limit']} calls left until {usage['reset_date']}")

TypeScript

const response = await fetch("https://api.asterwise.com/v1/keys/me/usage", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const { data: usage } = await response.json();
console.log(`${usage.calls_remaining} of ${usage.calls_limit} calls left until ${usage.reset_date}`);

Example response

{
  "success": true,
  "message": "success",
  "data": {
    "calls_used": 142,
    "calls_limit": 500,
    "calls_remaining": 358,
    "percent_used": 28.4,
    "tier": "sandbox",
    "burst_limit": 10,
    "reset_date": "2026-11-01",
    "period_start": "2026-10-01",
    "period_end": "2026-10-31"
  }
}

Response fields

Field	Type	Description
calls_used	integer	Successful calls the account has made this UTC month.
calls_limit	integer	The account's monthly call limit.
calls_remaining	integer	Calls left this month. Never below 0.
percent_used	number	calls_used as a percentage of calls_limit, to one decimal place.
tier	string	The plan the account is on now.
burst_limit	integer	Calls a minute the plan allows.
reset_date	string	The date the monthly count starts again (UTC).
period_start	string	First day of the current month (UTC).
period_end	string	Last day of the current month (UTC).

calls_remaining here and X-RateLimit-Remaining on your other answers come from the same counter, so they match. The dashboard shows your usage too.

See Rate Limits for what each limit allows and what a refusal looks like.