Developers

API

Usage & Limits

The Nebo API uses a cost-weighted budget system. Every request consumes budget based on the underlying cost of the model used — expensive models consume budget faster than cheap ones.

Checking Your Usage

GET /v1/usage

Returns your current plan, budget usage, and pool balances.

curl https://janus.neboloop.com/v1/usage \
  -H "Authorization: Bearer $NEBO_TOKEN"

Response

{
  "plan": "plus",
  "all_models": {
    "session_used": 1250000,
    "session_limit": 10000000,
    "session_reset_seconds": 14400,
    "weekly_used": 8400000,
    "weekly_limit": 50000000,
    "weekly_reset_seconds": 518400
  },
  "grants": {
    "free_available": 0,
    "gift_available": 750000
  },
  "credits": {
    "balance_cents": 1200
  }
}

All budget values are in microdollars (1 credit = $0.000001). Credit balances are in cents.

Budget Windows

Your usage is tracked across two rolling windows:

Window Duration Resets
Session 5 hours Rolling — oldest usage drops off continuously
Weekly 7 days Rolling — oldest usage drops off continuously

Both windows must have remaining budget for a request to proceed. If either is exhausted, you receive a 429 response.

Budget Pools

The API draws from four pools in priority order:

Pool Source Priority Description
Free New subscription 1st Starter credits granted when you subscribe to a plan
Gift Referrals 2nd Bonus credits earned through Nebo's gifting program
Plan Subscription 3rd Your plan's session and weekly budget
Credits Purchased top-ups 4th Pay-as-you-go credits (only used when plan budget is exhausted)

Free and gift pools are only available to subscribers. They are consumed first. Once depleted, your plan budget kicks in. If your plan budget is exhausted, purchased credits are used as overflow.

The X-Budget-Active-Pool response header tells you which pool funded each request.

Plan Tiers

Higher plans provide larger session and weekly budgets. Check your current plan and budget limits via the /v1/usage endpoint or the X-RateLimit-* response headers. See getnebo.com/download for plan details.

How Budget Is Consumed

Budget consumption depends on the model used and the length of the request. Simpler models cost less per request than advanced reasoning models. Smart routing (model: "auto") optimizes model selection automatically to get the best results for your budget.

Use the X-RateLimit-Session-Remaining-Credits header to track your remaining budget in real time.

Rate Limit Headers

Every chat completion response includes these headers:

Session Window

Header Description
X-RateLimit-Session-Limit-Credits Total session budget (microdollars)
X-RateLimit-Session-Remaining-Credits Remaining session budget
X-RateLimit-Session-Reset ISO 8601 timestamp when the session window resets

Weekly Window

Header Description
X-RateLimit-Weekly-Limit-Credits Total weekly budget (microdollars)
X-RateLimit-Weekly-Remaining-Credits Remaining weekly budget
X-RateLimit-Weekly-Reset ISO 8601 timestamp when the weekly window resets

Pool Balances

Header Description
X-Budget-Free-Available Remaining free credits
X-Budget-Gift-Available Remaining gift credits
X-Budget-Credits-Cents Purchased credit balance (in cents)
X-Budget-Active-Pool Which pool funded this request: free, gift, plan, or credits

Handling 429 Responses

When your budget is exhausted, the API returns HTTP 429:

{
  "error": {
    "message": "Session budget exhausted. Resets in 2h 15m.",
    "type": "rate_limit_error",
    "code": "USAGE_LIMIT_EXCEEDED"
  }
}

What to do:

  1. Check the X-RateLimit-Session-Reset header for when your budget refills
  2. Switch to cheaper models (direct selection) to stretch remaining budget
  3. Purchase credits for overflow capacity
  4. Upgrade your plan for higher budgets

Fail-Open Behavior

If the budget tracking system is temporarily unavailable (infrastructure hiccup), requests are allowed through rather than blocked. Usage is eventually consistent — your budget may briefly show stale numbers during recovery, but no usage is lost.

Next Steps

Embeddings Bring Your Own Key