How to check your API key balance and remaining quota#

To check how much quota is left on your key, send a GET request to the /v1/balance endpoint. It returns the remaining points for the key you pass — and, unlike every other endpoint, checking your balance does not consume any of those points. This reads the balance for one key:

curl "https://api.apitube.io/v1/balance?api_key=YOUR_API_KEY"

You can pass the key as the api_key query parameter or as an X-API-Key header. The endpoint is read-only and accepts GET only.

What does the /v1/balance endpoint return?#

/v1/balance returns a small JSON object that echoes your key and reports the points remaining on the account it belongs to:

{
  "api_key": "YOUR_API_KEY",
  "points": 1500
}

The points field is your remaining request quota — the same pool that normal search and retrieval calls draw from. Every successful call to an endpoint like /v1/news/everything deducts one point, so points tells you how many standard requests you have left before you run out.

How do I authenticate a balance request?#

/v1/balance accepts your API key in any of three ways — the same options every News API endpoint supports:

• Authorization header — Authorization: Bearer YOUR_API_KEY
• X-API-Key header — X-API-Key: YOUR_API_KEY
• Query parameter — ?api_key=YOUR_API_KEY

Using the header keeps your key out of URLs and server logs, which is the safer choice for anything server-side:

curl "https://api.apitube.io/v1/balance" \
  -H "X-API-Key: YOUR_API_KEY"

Does checking your balance cost anything?#

No. A call to /v1/balance does not deduct any points, so you can check your remaining quota as often as you need without eating into it. It is still an authenticated request, so it counts toward the per-minute rate limit: 50 requests per minute on a live key (15 on a test key), and repeated violations lead to a temporary ban after 30 of them. Don’t poll it in a tight loop — check it on a sensible schedule (for example, once a minute or before a batch job) rather than on every single request.

How to read your plan and balance from the response headers#

You don’t always need a separate balance call. Every authenticated response from the News API — including /v1/balance itself — carries a set of headers that report your current state:

• x-points-remaining — remaining request quota (same number as the points field)
• x-subscription-plan — your current plan (for example basic), or free
• x-balance-remaining — your pay-as-you-go balance, in cents
• x-apitube-mode — live or test, so you know which key you used
• x-budget-remaining — present only when a monthly pay-as-you-go limit is set

Because these come back on ordinary requests, you can track quota straight from your search responses and reserve /v1/balance for a dedicated, content-free check. If you only need a number from your data instead of your account, count matching articles without downloading them follows the same lightweight pattern.

When should you check your balance?#

Use /v1/balance whenever you want to know your standing before it bites you:

• Avoid running out mid-job — normal endpoints return 402 with error code ER0176 once your points hit zero; checking ahead lets you top up or pause first.
• Dashboards and alerts — surface remaining points to your team, or fire a warning when the number drops below a threshold.
• CI and deploy checks — confirm a key still has quota before a scheduled pipeline depends on it.

For the full picture of how keys and credentials work, see the official authentication guide on the APITube docs.

Common Questions#

• Does checking my balance use a request?
• What does the points number mean?
• Can I see my balance without a separate call?
• What errors can /v1/balance return?

Does checking my balance use a request?#

It does not spend any points — the balance check is free in quota terms. It is still a real HTTP request, so it counts toward the per-minute rate limit (50/min on a live key, 15/min on a test key). In short: it won’t drain your quota, but don’t hammer it.

What does the points number mean?#

points is your remaining standard request quota. Endpoints such as /v1/news/everything, /v1/news/top-headlines and /v1/news/count each deduct one point per successful call. When points reaches zero, those endpoints return 402 (ER0176) until you upgrade, top up, or your quota resets.

Can I see my balance without a separate call?#

Yes. Every authenticated response includes the x-points-remaining header, so you can read your remaining quota directly from any search or retrieval response without calling /v1/balance at all. The companion headers x-subscription-plan and x-balance-remaining report your plan and pay-as-you-go balance on the same responses.

What errors can /v1/balance return?#

If the key is missing you get 401 (ER0201); if it is invalid you get 401 (ER0202); an expired key returns 401 (ER0230). Exceeding the rate limit returns 429 (ER0203), and continued abuse triggers a temporary ban (ER0204). Each error response carries a request id you can quote to support.