> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-guide/integrations.md).

# Billing & Credits

API operations that consume resources are billed in **credits**. Credits are checked before executing the operation — if you don't have enough, the request is rejected with `402`.

### Credit Costs

| Operation                   | Credits      | Endpoint                   |
| --------------------------- | ------------ | -------------------------- |
| Create agent                | 10           | `POST /agents`             |
| Update agent                | 10           | `PUT /agents/{id}`         |
| Start agent                 | 5            | `POST /agents/{id}/start`  |
| Reload config               | 1            | `POST /agents/{id}/reload` |
| Chat message                | 1 + LLM cost | `POST /agents/{id}/chat`   |
| Stop / Pause / Delete agent | 0            | —                          |
| All read operations (GET)   | 0            | —                          |
| Key management              | 0            | —                          |

> Credit costs are provisional and subject to change.

**Chat billing note**: The base credit (1) is charged on successful completion. The LLM cost (model-dependent token usage) is charged separately by the runtime, same as when using the web UI.

### Checking Your Balance

```
GET /billing/credits
```

**Auth**: Master key only.

```
curl https://api.guayaba.run/api/v1/billing/credits \
  -H "Authorization: Bearer g_master_YOUR_KEY"
```

**Response**:

```
{
  "success": true,
  "data": {
    "total_credits": 450,
    "subscription_credits": 400,
    "purchased_credits": 50
  }
}
```

### Subscription Info

```
GET /billing
```

Returns your current subscription details (tier, status, period dates, trial info).

**Auth**: Master key only.

### Available Tiers

```
GET /billing/tiers
```

Returns all subscription tiers with pricing, credit allowances, and feature lists.

**Auth**: Master key only.

### Insufficient Credits

When you don't have enough credits for an operation, the API returns:

```
402 Payment Required
{
  "error": "Payment Required",
  "message": "Insufficient credits for this operation",
  "required_credits": 10,
  "available_credits": 3
}
```

The operation is **not** executed. No credits are deducted.

### Subscription Requirement

All API endpoints require an active subscription (`active` or `trialing` status). If your subscription is canceled, past due, or absent:

```
403 Forbidden
{
  "error": "Forbidden",
  "message": "An active subscription is required to use the API"
}
```
