# 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"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.guayaba.run/documentation/api-guide/integrations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.