# 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.