> 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" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.guayaba.run/documentation/api-guide/integrations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.