Usage

GET /v1/usage returns your plan, a usage rollup grouped by (surface, region) covering the last 30 days (UTC-day aligned), and your remaining credit balance. The daily series spans a wider 90-day trend window. It’s a read-only snapshot — nothing here mutates state.

Request

curl https://api.aisearchapi.dev/v1/usage \
  -H "Authorization: Bearer $AISEARCH_API_KEY"

const res = await fetch('https://api.aisearchapi.dev/v1/usage', {
  headers: { Authorization: `Bearer ${process.env.AISEARCH_API_KEY}` },
});
const usage = await res.json();

import os, requests

res = requests.get(
    "https://api.aisearchapi.dev/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
)
usage = res.json()

This endpoint takes no parameters. It requires a valid Authorization: Bearer <API_KEY> header like every authenticated route.

Response

{
  "plan": "free",
  "usage": {
    "byGroup": [
      {
        "surface": "chatgpt",
        "region": "us",
        "callCount": 540,
        "creditsCharged": 2700
      },
      {
        "surface": "claude",
        "region": "us",
        "callCount": 388,
        "creditsCharged": 2328
      },
      {
        "surface": "perplexity",
        "region": "GLOBAL",
        "callCount": 262,
        "creditsCharged": 786
      }
    ],
    "totals": { "callCount": 1190, "creditsCharged": 5814 }
  },
  "balance": {
    "plan": "free",
    "credits": 236,
    "unlimited": false
  }
}

plan

string

Your current plan identifier.

usage

object

Your usage ledger, rolled up by the never-blended (surface, region) key.

Show usage

usage.byGroup

object[]

One entry per distinct (surface, region) combination you have run. surface is the surface enum value, region the canonical region key (lowercased country[:city][:language], or GLOBAL for untargeted). callCount is the number of child captures; creditsCharged the credits billed for them.

usage.totals

object

{ callCount, creditsCharged } summed across every group.

balance

object

Your remaining credit balance.

Show balance

balance.plan

string

Plan identifier for the balance, matching the top-level plan.

balance.credits

number | null

Credits remaining. null until your first submit seeds the balance (new accounts are seeded with 500 credits on first use).

balance.unlimited

boolean

true only on unmetered (internal) access, where credits is null and captures don’t draw down a balance. false on customer keys.

Per-child accounting

Usage is counted per child capture, not per request. A single POST /v1/search fans out into one child per surface × region, and each child is recorded independently against its exact (surface, region) group. A search across N surfaces and M regions produces N × M child captures. For example, surfaces: ["chatgpt", "claude", "perplexity"] with regions: [{ "country": "US" }, { "country": "GB" }] is 3 × 2 = 6 captures, adding 6 to totals.callCount across six groups.

Credits vs. calls

callCount counts captures; creditsCharged tracks what they cost. They’re related but not identical: a capture only draws down credits when it succeeds. An empty capture (surfacePresent: false) or a failed one is not billed. Per-capture credit costs vary by surface. See Credits & pricing for the full table.

Internal (first-party) keys can scope this read to a single tenant with the ?owner= query parameter or the X-AISearch-On-Behalf-Of header; the enforced owner is echoed back in the body (owner) and the X-AISearch-Owner header. Customer (sk_*) keys are always scoped to their own account — an override is ignored.

Credits & pricing

What each capture costs and how billing works.

Job lifecycle

How parent and child jobs move through terminal states.

Endpoints

Account & discovery

Watches

By surface

Request

Response

Per-child accounting

Credits vs. calls

Credits & pricing

Job lifecycle

​Request

​Response

​Per-child accounting

​Credits vs. calls

Credits & pricing

Job lifecycle

Request

Response

Per-child accounting

Credits vs. calls