Plans & usage

How billing counts

TNL meters a monthly call allowance. There is no per-second rate limit, and no burst budget to manage — the only ceiling is how many calls you make in a calendar month.

Two separate meters exist:

Meter	Scope	Allowance
API calls	Every authenticated REST and MCP request	Set by your plan
Ledger AI Terminal questions	/v1/ai-terminal and /v1/ai-terminal/chat only	50 per month

A Ledger AI Terminal request consumes both: one API call and one Terminal question. The Terminal question is reserved before model work begins, so an abandoned or failed investigation can still consume the reservation.

Current pricing and plan tiers live on the plans page — they change, so this page does not duplicate them.

Reading your usage

GET /v1/me is the authoritative source:

curl -sS "https://theneuralledger.com/v1/me" \
  -H "Authorization: Bearer $TNL_API_KEY"

{
  "key": { "…": "key metadata" },
  "plan": { "…": "resolved plan" },
  "usage": {
    "month": "2026-07",
    "calls": 1284,
    "remaining": 8716,
    "monthlyLimit": 10000,
    "resetAt": "2026-08-01T00:00:00.000Z"
  }
}

Field	Type	Meaning
month	string	Billing month, YYYY-MM.
calls	number	Calls consumed so far this month.
remaining	number | null	Calls left. null on uncapped plans.
monthlyLimit	number | null	Plan ceiling. null on uncapped plans.
resetAt	string	ISO timestamp when the counter resets.

MCP tool responses carry the same usage block, so an MCP client can track its position without a separate REST call.

Budgeting

Each page is a call, not each story. At page_size=100:

Task	Calls
10,000-story backfill	100
Hourly sync, 1 page each	~720/month
Hourly sync, 3 pages each	~2,160/month

Practical ways to spend fewer calls:

• Use page_size=100 rather than the default — same data, fewer requests.
• Poll with updated_since so you fetch only what changed.
• Use fields to shrink responses (this reduces bandwidth and parse cost, though the call count is unchanged).
• Cache aggressively. Stories change only when revision increments.

A 429 will not clear on retry

429 means the monthly allowance is exhausted. It resets at usage.resetAt — not in a few seconds. Retrying immediately accomplishes nothing. See Errors & rate limits.

Uncapped plans

When monthlyLimit and remaining are null, the plan has no fixed ceiling. Code defensively — do not assume these fields are numbers:

const { remaining, monthlyLimit } = usage;
const unlimited = monthlyLimit === null;
const low = !unlimited && remaining < monthlyLimit * 0.1;
if (low) console.warn(`TNL allowance low: ${remaining} calls left`);