GET /v1/usage returns your account plan, a per-surface job tally, and your remaining credit balance. It’s a read-only snapshot — nothing here mutates state.

​
Request

curl https://api.aisearchapi.dev/v1/usage \
  -H "Authorization: Bearer $AISEARCH_API_KEY"
This endpoint takes no parameters. It requires a valid Authorization: Bearer <API_KEY> header like every authenticated route.

​
Response

{
  "plan": "growth",
  "usage": {
    "totalJobs": 1432,
    "bySurface": {
      "chatgpt": 540,
      "claude": 388,
      "perplexity": 262,
      "gemini": 21,
      "copilot": 10,
      "google_ai_overview": 142,
      "google_ai_mode": 69
    }
  },
  "balance": {
    "plan": "growth",
    "credits": 512340,
    "unlimited": false
  }
}
​
plan
string
Your current plan identifier (for example growth).
​
usage
object
Lifetime job counts for your account.
​
balance
object
Your remaining credit balance.

​
Per-child accounting

Usage is counted per child job, not per request. A single POST /v1/search fans out into one child per surface × region, and each child is counted independently. A search across N surfaces and M regions produces N × M child jobs. For example, surfaces: ["chatgpt", "claude", "perplexity"] with regions: [{ "country": "US" }, { "country": "GB" }] is 3 × 2 = 6 jobs, adding 6 to totalJobs (2 to each of those three surfaces in bySurface).
totalJobs is exactly the sum of all bySurface values. If you tally them yourself, they reconcile.

​
Credits vs. jobs

usage counts jobs; balance tracks credits. They’re related but not identical: a job only draws down credits when it produces a successful capture. An empty capture (surfacePresent: false) or a failed one costs nothing, so it can appear in bySurface and totalJobs without reducing credits. Per-capture credit costs vary by surface. See Credits & pricing for the full table.
On unmetered plans, balance.credits is null and balance.unlimited is true. Branch on unlimited rather than assuming credits is a number.

Credits & pricing

What each capture costs and how billing works.

Job lifecycle

How parent and child jobs move through terminal states.