> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naga.ac/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance and Activity

> Inspect account balance, request volume, costs, top models, and per-key activity.

Use the account billing and activity endpoints to monitor spend and operational usage.

Both endpoints require a provisioning key.

## Endpoints at a glance

| Endpoint                          | What it returns                                                |
| --------------------------------- | -------------------------------------------------------------- |
| `GET /v1/account/balance`         | Current account balance                                        |
| `GET /v1/account/activity?days=N` | Requests, token usage, costs, top models, and per-key activity |

## Why These Endpoints Matter

Use them to:

* monitor remaining funds before expensive operations
* analyze usage by model, day, or API key
* build internal dashboards or budget alerts
* attribute spend across projects or environments

## Get Balance

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.naga.ac/v1/account/balance",
      headers={"Authorization": "Bearer YOUR_PROVISIONING_KEY"},
  )
  response.raise_for_status()

  balance = response.json()
  print(balance["balance"])
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.naga.ac/v1/account/balance', {
    headers: {
      Authorization: 'Bearer YOUR_PROVISIONING_KEY',
    },
  });

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  const balance = await response.json();
  console.log(balance.balance);
  ```

  ```bash cURL theme={null}
  curl https://api.naga.ac/v1/account/balance \
    -H "Authorization: Bearer YOUR_PROVISIONING_KEY"
  ```
</CodeGroup>

Response shape:

```json theme={null}
{
  "balance": "42.50"
}
```

The balance is returned as a string representing a USD amount.

## Get Activity

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.naga.ac/v1/account/activity",
      headers={"Authorization": "Bearer YOUR_PROVISIONING_KEY"},
      params={"days": 7},
  )
  response.raise_for_status()

  activity = response.json()
  print(activity["total_stats"]["total_requests"])
  print(activity["total_stats"]["total_cost"])
  ```

  ```javascript Node.js theme={null}
  const url = new URL('https://api.naga.ac/v1/account/activity');
  url.searchParams.set('days', '7');

  const response = await fetch(url, {
    headers: {
      Authorization: 'Bearer YOUR_PROVISIONING_KEY',
    },
  });

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  const activity = await response.json();
  console.log(activity.total_stats.total_requests);
  console.log(activity.total_stats.total_cost);
  ```

  ```bash cURL theme={null}
  curl "https://api.naga.ac/v1/account/activity?days=7" \
    -H "Authorization: Bearer YOUR_PROVISIONING_KEY"
  ```
</CodeGroup>

The activity payload includes:

* total requests and total cost
* token usage
* daily breakdowns
* top models
* per-key usage

Use the optional `days` query parameter to control the lookback window. The supported range is `1-30`, with a default of `30`.

Results are cached briefly for performance, so clients should avoid assuming fully uncached real-time aggregation.

## Practical Uses

* trigger low-balance alerts
* find the most expensive model families in the last week or month
* compare production vs staging usage if each environment has its own API key
* attribute spend back to teams or internal services

## Related Docs

* [Account Management](/account/account-management)
* [API Keys](/account/api-keys)
* [How Billing Works](/build/billing)

## Related Reference Pages

* [Get account balance](/api-reference/endpoints/account/balance)
* [Get account activity](/api-reference/endpoints/account/activity)