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

# Billing

> Query AI credit usage, budgets, billing overview, adoption metrics, and credit alerts through the Collate REST API

# Billing

The Billing API reports how your workspace consumes AI credits: overall usage, budgets and ceilings, per-user and per-source breakdowns, adoption trends, and MCP tool usage. Most endpoints are read-only reporting. A smaller set lets an admin configure credit budgets and alerts.

Every endpoint under `/v1/billing` requires authentication. Unless noted otherwise, an endpoint requires the calling user to be a workspace admin. A handful of "my" endpoints are self-service and return only the calling user's own data.

## Feature Usage and Limits

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/billing/usage/{name}` | Configured limits for one feature, or all features with `name=all`. Doesn't include current usage counts. |

## AI Credit Budgets

A budget is a ceiling (`RateLimit`) on AI credit spend over a recurring window (hourly through yearly), optionally scoped to `total` usage or per-user.

Budget endpoints were added after Collate 2.0.2. Requests to them on 2.0.2 return `404`.

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/billing/budgets` | All configured credit ceilings, with consumption in the current window. |
| `PUT` | `/v1/billing/budgets` | Replace the entire set of ceilings. A ceiling left out of the request is removed. An empty list is rejected. |
| `DELETE` | `/v1/billing/budgets` | Remove all ceilings, leaving only the workspace-wide credit pool. |
| `GET` | `/v1/billing/budgets/me` | Ceilings that apply to the calling user, with their own consumption. Self-service: any authenticated user. |

`PUT /v1/billing/budgets` takes a `budgets` array (required) of `RateLimit` objects, each with `window` (required: `HOURLY`, `FOURHOURS`, `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`, or `GLOBAL`), `credits` (required), and `scope` (`total` or `user`, defaults to `total`).

## Credit Usage and Breakdowns

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/billing/credits/summary` | Full credit usage breakdown across app-based and entity-based usage. |
| `GET` | `/v1/billing/credits/remaining` | Total remaining credits after all usage. |
| `GET` | `/v1/billing/credits/conversations` | Credits consumed per conversation ID over a time window. Unattributed spend is grouped under `"unattributed"`. |
| `GET` | `/v1/billing/credits/apps` | Per-app, per-action credit usage, with raw usage and converted credits. |
| `GET` | `/v1/billing/credits/apps/history` | Historical credit usage across all apps, by app and date. Requires `startTs`. Ignores `endTs`. |
| `GET` | `/v1/billing/credits/entities` | Entity-based credit usage (assets, users, test cases). |
| `GET` | `/v1/billing/credits/breakdown/users` | Credit consumption grouped by user for the current cycle. |
| `GET` | `/v1/billing/credits/breakdown/users/{userName}/agents` | One user's credit usage broken down by agent or source. |
| `GET` | `/v1/billing/credits/breakdown/sources` | Credit consumption grouped by application source (for example, `openmetadata`, `slack`, `teams`). |
| `GET` | `/v1/billing/credits/breakdown/cross` | Nested breakdown: user name → application source → credits. |
| `GET` | `/v1/billing/credits/me/breakdown/sources` | The calling user's own per-source credit breakdown. Self-service. |
| `GET` | `/v1/billing/credits/me/breakdown/actions` | The calling user's own per-action credit breakdown. Self-service. |
| `GET` | `/v1/billing/credits/me/breakdown/cross` | The calling user's own source → action → credits breakdown. Self-service. |

Most time-windowed endpoints accept `startTs` and `endTs` (epoch milliseconds). `/v1/billing/credits/apps/history` requires `startTs` and ignores `endTs`, so its results cannot be bounded by an end time. The `users`, `sources`, `cross`, and `users/{userName}/agents` credit-breakdown endpoints accept an optional `app` query parameter to filter to one application.

## Billing Overview and Adoption

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/billing/overview` | Single-call billing overview: plan, usage meters, credit summary, and the last 7 days as a series. |
| `GET` | `/v1/billing/weekly-impact` | Weekly Impact Dashboard snapshot, comparing the last 7 complete UTC days against the prior window by default. |
| `POST` | `/v1/billing/weekly-impact/send-digest` | Build the same snapshot and email it to every active, non-bot admin. |
| `GET` | `/v1/billing/adoption` | Adoption metrics from telemetry: active-user series, activation funnel, feature adoption, per-user aggregates. Accepts `weeks` and `days`. |
| `GET` | `/v1/billing/adoption/summary` | A lighter adoption summary plus the weekly active-user series. Accepts `weeks`. |
| `GET` | `/v1/billing/adoption/users` | Paginated billable-user directory, including never-activated, dormant, and soft-deleted users, with 30-day aggregates. Accepts `page`, `pageSize`, `search`, `status`, `sort`, `direction`. |
| `GET` | `/v1/billing/conversations/daily` | Conversation counts and distinct senders per UTC day. Days with no activity are returned as zero. |

## MCP Usage

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/billing/mcp/usage/summary` | MCP usage summary aggregated over a time window. |
| `GET` | `/v1/billing/mcp/usage/history` | Daily MCP usage as a map of ISO date to success/failure counts. |
| `GET` | `/v1/billing/mcp/usage/breakdown/tools` | Per-tool MCP usage: call count, error count, and latency. |
| `GET` | `/v1/billing/mcp/usage/breakdown/users` | Per-user MCP usage: call count and client. |

## Credit Alerts

A credit alert notifies configured destinations when spend crosses a threshold, such as a percentage of the credit pool used or an unusual daily spike.

Credit-alert endpoints were added after Collate 2.0.2. Requests to them on 2.0.2 return `404`.

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/billing/creditAlert` | The configured alert. Returns `404` if none is configured. |
| `PUT` | `/v1/billing/creditAlert` | Create or replace the alert's rules and destinations. |

`PUT /v1/billing/creditAlert` takes `rules` (array of alert rules, default empty), `destinations` (array of event subscription destinations, default empty), and `enabled` (default `true`). Each rule has a `type` (required: `poolPercentUsed`, `dailyCredits`, `dailySpike`, `runCredits`, or `runwayDays`), `thresholds`, and for `dailySpike` a `multiplier` and `minAbsolute`.

## Example

These requests return the remaining credits and, on releases with budget support, set a monthly budget.

<RequestExample>
  ```bash Get remaining credits theme={null}
  curl "{base_url}/api/v1/billing/credits/remaining" \
    -H "Authorization: Bearer {access_token}"
  ```

  ```bash Set a monthly credit budget theme={null}
  curl -X PUT "{base_url}/api/v1/billing/budgets" \
    -H "Authorization: Bearer {access_token}" \
    -H "Content-Type: application/json" \
    -d '{
      "budgets": [
        { "window": "MONTHLY", "credits": 500000, "scope": "total" }
      ]
    }'
  ```
</RequestExample>