Skip to Content

Account & Balance

Every task draws on three quotas of the account: steps, the actions an LLM agent takes (a natural-language task only), traffic_bytes, the bytes the browser moved, and browser_seconds, the time a browser was busy with the task. A task is billed only when it succeeded (see Billing). When a quota reaches zero and there is no USD balance to cover overage, creating a task is refused with 402.

This endpoint says where the account stands before that happens, and the same warning rides on every task reply, so a client hears about a low balance while it can still do something about it.

GET /api/v1/account/balance

curl -sS "https://llm.dat.ai/api/v1/account/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200), an account whose browser time has run out:

{
  "account": { "uid": "acc_...", "status": "active" },
  "subscription": { "status": "active", "plan": "free", "plan_name": "Free" },
  "balance": {
    "steps": { "remaining": 28, "included": 200, "unit": "action" },
    "traffic_bytes": { "remaining": 169218973, "included": 500000000, "unit": "gigabyte" },
    "browser_seconds": { "remaining": 0, "included": 1800, "unit": "hour" },
    "usd": { "remaining": 0 }
  },
  "can_run": { "task": false, "script": false, "search": false },
  "blocked": "insufficient balance: the browser_seconds quota is used up and the USD balance is 0.00",
  "exhausted": ["browser_seconds"],
  "low": [],
  "warning": "browser_seconds quota used up and the USD balance is 0.00; tasks that need it are refused with 402. Top up in the dashboard (https://dash.dat.ai); GET /api/v1/account/balance has the figures."
}
FieldMeaning
balance.<quota>.remainingWhat is left of the quota, in its own unit: actions, bytes, seconds
balance.<quota>.includedWhat the plan included for the period; 0 when the plan states no amount
balance.<quota>.unitThe unit the quota is priced in
balance.usd.remainingThe USD balance in dollars. Overage is charged here, so it can be negative
can_run.taskWhether a natural-language task may start now: steps, traffic_bytes and browser_seconds above zero, or a positive USD balance
can_run.scriptThe same for a custom script, which spends no steps
can_run.searchThe same for a SERP or AI search request, which spends no steps either
blockedWhy a task may not start, when it may not: the quota, or the account or subscription state
exhaustedThe quotas at zero
lowThe quotas under a tenth of what the plan included, not yet at zero
warningThe sentence the task replies carry, empty when every quota is comfortable

An account with room in every quota answers with empty exhausted and low, no blocked and no warning:

{
  "account": { "uid": "acc_...", "status": "active" },
  "subscription": { "status": "active", "plan": "free", "plan_name": "Free" },
  "balance": {
    "steps": { "remaining": 173, "included": 200, "unit": "action" },
    "traffic_bytes": { "remaining": 412887340, "included": 500000000, "unit": "gigabyte" },
    "browser_seconds": { "remaining": 1522, "included": 1800, "unit": "hour" },
    "usd": { "remaining": 0 }
  },
  "can_run": { "task": true, "script": true, "search": true },
  "exhausted": [],
  "low": []
}

Errors: 401 (missing or invalid API key):

{ "error": "Authentication required: missing Authorization header. Please provide Authorization header with Bearer token format: 'Authorization: Bearer <your-api-key>'" }

The warning on task replies

The same warning comes back with every task while it is not empty:

  • balance_warning in the JSON of POST /api/v1/browsing/async and POST /api/v1/browsing/sync;
  • the X-Balance-Warning header on every task reply, the SERP page included;
  • balance_warning in the result of every MCP tool that starts a task.

It is absent while every quota is above a tenth of what the plan included. A client that watches for it sees a session’s end coming several tasks ahead; a client that does not still gets the plain 402.

When a task is refused

{
  "error": "Insufficient balance: the browser_seconds quota is used up and there is no USD balance to cover overage; top up in the dashboard (https://dash.dat.ai) or check GET /api/v1/account/balance",
  "code": "insufficient_balance",
  "exhausted": "browser_seconds"
}

The refusal is decided when the task is created; a task already running is never stopped for balance. Top up in the dashboard , or wait for the plan’s next period.

MCP

The account_balance tool returns this endpoint’s JSON. An agent that runs long sessions can call it first and plan the session against balance and can_run; every task tool also returns balance_warning when there is one.

AuthenticationSupply