API reference

Account

GET /v1/agents/account

Returns the plan and spendable credit of the account behind the key. Use it to decide whether to start a task, or to explain a task that stopped for lack of credits.

Request

bash

curl -s "$SAI_API_URL/v1/agents/account" \
  -H "Authorization: Bearer $SAI_API_KEY"

Response

json

{
  "userId": "3fA9kQ2xYz",
  "userState": "active",
  "plan": {
    "id": "sai_subscription",
    "title": "Sai Subscription",
    "free": false,
    "unlimited": false
  },
  "credits": { "usd": 12.4 },
  "authType": "apiKey"
}

Field	Notes
`userId`	The account id. Also the `uid` in `approvalUrl`.
`userState`	The account state string. `null` when unknown.
`plan.id`	The subscription plan id. `null` on the free plan.
`plan.title`	A display name: `Free`, `Sai Subscription`, `Sai Premium Subscription`, `Sai Unlimited Subscription`, `Sai Pay As You Go`. An unknown plan id is returned as is.
`plan.free`	`true` on the free plan.
`plan.unlimited`	`true` on the unlimited plan.
`credits`	`{ "usd": number }`. `null` when Billing could not be reached; the rest of the response is still filled.
`credits.usd`	Spendable credit in US dollars, two decimals. `null` on the unlimited plan.
`authType`	`apiKey` or `firebase`.

A free account:

json

{
  "userId": "3fA9kQ2xYz",
  "userState": "active_free",
  "plan": { "id": null, "title": "Free", "free": true, "unlimited": false },
  "credits": { "usd": 0.35 },
  "authType": "apiKey"
}

Gotchas

The call never fails because Billing is down. Check credits for null before reading credits.usd.
Credit is what a task can spend now. A free account's daily grant refills it; the portal shows when.
The Billing lookup has a five-second timeout, so this call can take a moment. Do not put it inside the poll loop.