Check your balance with /v1/balance

/v1/balance returns how many points an API key has left and which plan it is on. Call it before a large batch job, or on a schedule to alert when a key is running low.

The call itself is free — it does not consume points.

Endpoint

GET /v1/balance

Base URL: https://api.apitube.io.

Authentication

Any of the three standard methods work — see Authentication:

curl "https://api.apitube.io/v1/balance" -H "X-API-Key: YOUR_API_KEY"
curl "https://api.apitube.io/v1/balance" -H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.apitube.io/v1/balance?api_key=YOUR_API_KEY"

The balance returned always belongs to the key used to authenticate — a key cannot read another key's balance.

Parameters

This endpoint takes no parameters other than authentication — see Authentication.

Response format

{
  "api_key": "ak_live_abc123...",
  "points": 48500,
  "plan": "professional"
}

Response fields

Field	Type	Description
api_key	string	The key the balance belongs to
points	integer	Points remaining
plan	string	Current subscription plan

What a point costs

Request	Points
Any article, count or trends request	1
Reference directories — People, Companies, Journalists	1
/v1/news/local	1 + 1 per requested insights block
/v1/fact-check	5
Adding the prompt parameter	+2 for the translation step (Basic and above only)
/v1/suggest/* autocomplete	0
/v1/news/event-types	0
/v1/balance	0

A request is charged only when it returns something: a search with zero results, and a directory lookup with no matches, cost nothing.

The real-time channels bill from their own pools rather than from points: SSE spends sse_points, WebSocket spends ws_points and webhooks spend webhook_points — one credit per delivered article in each case, while idle connections, heartbeats and empty polls are free. Points are separate from the per-minute rate limit — see Rate limits and quotas.

Request examples

cURL

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

Python

import requests

balance = requests.get(
    "https://api.apitube.io/v1/balance",
    headers={"X-API-Key": "YOUR_API_KEY"},
).json()

if balance["points"] < 1000:
    print(f"Low balance: {balance['points']} points left on {balance['plan']}")

Node.js

const response = await fetch('https://api.apitube.io/v1/balance', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const balance = await response.json();

console.log(`${balance.points} points left on ${balance.plan}`);

PHP

$context = stream_context_create(['http' => ['header' => 'X-API-Key: YOUR_API_KEY']]);
$balance = json_decode(file_get_contents('https://api.apitube.io/v1/balance', false, $context), true);

echo $balance['points'], ' points left on ', $balance['plan'], PHP_EOL;

Errors

Code	Status	Meaning
ER0201	401	No API key in the request
ER0202	401	API key is invalid

Full list in HTTP response codes.

Related

• Rate limits and quotas — per-minute limits and per_page ceilings by plan.
• Authentication — the three ways to pass a key.