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

# Billing & usage

> Inspect credit balances and usage, then fund organizations and tenants.

AutoSage meters model usage in credits. Tenant endpoints expose the balance and request-level usage; organization endpoints aggregate and allocate credits across tenants.

## Endpoints

| Method | Path                                          | Description                                  | Auth                       |
| ------ | --------------------------------------------- | -------------------------------------------- | -------------------------- |
| `GET`  | `/billing/tenants/:tenantId/credits`          | Get a tenant credit balance                  | \[User+Key] `tenants:read` |
| `GET`  | `/billing/tenants/:tenantId/usage/summary`    | Get tenant usage totals                      | \[User+Key] `tenants:read` |
| `GET`  | `/billing/tenants/:tenantId/usage/logs`       | List tenant usage records                    | \[User+Key] `tenants:read` |
| `POST` | `/billing/organizations/:orgId/credits`       | Add credits to an organization               | \[User] admin              |
| `POST` | `/billing/tenants/:tenantId/credits`          | Allocate organization credits to a tenant    | \[User] admin              |
| `GET`  | `/billing/organizations/:orgId`               | Get organization billing and tenant balances | \[User]                    |
| `GET`  | `/billing/organizations/:orgId/usage/summary` | Get organization usage totals                | \[User]                    |
| `GET`  | `/billing/organizations/:orgId/usage/logs`    | List organization usage records              | \[User]                    |

<Note>
  Tenant read endpoints accept either a user session or an API key with `tenants:read` and access to the tenant. Organization billing endpoints require a user session; credit writes require `owner` or `billing_admin`.
</Note>

## Tenant billing

### Get a credit balance

`GET /billing/tenants/:tenantId/credits`

Returns `credits_pool`, `credits_used`, and `credits_available`, where available credits are the allocated pool minus usage.

<ParamField path="tenantId" type="string" required>
  Tenant ID.
</ParamField>

```bash theme={null}
curl "https://api.autosage.ai/api/v1/billing/tenants/TENANT_ID/credits" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

<Warning>
  When a tenant has insufficient credits, new chat or agent work can be rejected and scheduled runs are recorded as failed for insufficient credits. Allocate more credits before retrying.
</Warning>

***

### Get a usage summary

`GET /billing/tenants/:tenantId/usage/summary`

Returns aggregate credits, tokens, input tokens, output tokens, and message count for the tenant.

<ParamField path="tenantId" type="string" required>
  Tenant ID.
</ParamField>

***

### List usage logs

`GET /billing/tenants/:tenantId/usage/logs`

Returns paginated request-level records with model, token counts, credits used, related chat, caller key, and timestamp information.

<ParamField path="tenantId" type="string" required>
  Tenant ID.
</ParamField>

<ParamField query="start_date" type="string">
  Start date in `YYYY-MM-DD` format.
</ParamField>

<ParamField query="end_date" type="string">
  End date in `YYYY-MM-DD` format.
</ParamField>

<ParamField query="limit" type="number">
  Number of results to return, from 1 to 500. The default is 50.
</ParamField>

<ParamField query="offset" type="number">
  Number of records to skip.
</ParamField>

<ParamField query="api_key_id" type="string">
  Return usage attributed to a specific API key.
</ParamField>

<ParamField query="is_api_key" type="boolean">
  Return only API-key-driven usage when `true`.
</ParamField>

```bash theme={null}
curl "https://api.autosage.ai/api/v1/billing/tenants/TENANT_ID/usage/logs?start_date=2026-07-01&limit=50" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

***

### Allocate credits to a tenant

`POST /billing/tenants/:tenantId/credits`

Moves available organization credits into the tenant's credit pool.

<ParamField path="tenantId" type="string" required>
  Tenant to fund.
</ParamField>

<ParamField body="amount" type="number" required>
  Credits to allocate, greater than zero and no more than 1,000,000.
</ParamField>

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/billing/tenants/TENANT_ID/credits" \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 100 }'
```

## Organization billing

### Add organization credits

`POST /billing/organizations/:orgId/credits`

Adds credits to the organization's current billing pool.

<ParamField path="orgId" type="string" required>
  Organization ID.
</ParamField>

<ParamField body="amount" type="number" required>
  Credits to add, greater than zero and no more than 1,000,000.
</ParamField>

### Get organization billing

`GET /billing/organizations/:orgId`

Returns the current billing period, total allocated and used credits, available credits, status, and each tenant's allocation and usage.

<ParamField path="orgId" type="string" required>
  Organization ID.
</ParamField>

### Get organization usage summary

`GET /billing/organizations/:orgId/usage/summary`

Returns aggregate credit, token, and message totals across the organization's tenants.

<ParamField path="orgId" type="string" required>
  Organization ID.
</ParamField>

### List organization usage logs

`GET /billing/organizations/:orgId/usage/logs`

Accepts the same `start_date`, `end_date`, `limit`, `offset`, `api_key_id`, and `is_api_key` filters as tenant usage logs, then returns matching records across the organization.

<ParamField path="orgId" type="string" required>
  Organization ID.
</ParamField>

<Tip>
  Use tenant logs for customer-level cost attribution and organization logs for finance reporting. The [rate limits](/developers/rate-limits) page covers throughput controls, which are separate from credit balance.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Tenants" icon="box" href="/developers/api/tenants">
    Configure tenant quotas and initial credit pools.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/developers/rate-limits">
    Understand request throttling separately from credits.
  </Card>

  <Card title="Organizations" icon="building" href="/developers/api/organizations">
    Manage the top-level billing owner.
  </Card>
</CardGroup>