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

# Usage & Limits

> Credit-based usage, purchasing credits, and rate limiting for the Stewrd API.

## Credit-Based Usage

Each API request costs **credits** based on the capabilities used. Credits pay for orchestration, tool execution, sandboxing, and file storage — your own LLM key covers the AI inference (see [BYOK](/byok)).

| Capability | Credits | Description                          |
| :--------- | :------ | :----------------------------------- |
| Chat       | 1       | Conversational AI                    |
| Data       | 1       | Structured data processing           |
| Files      | 2       | File upload/download via signed URLs |
| Research   | 3       | Web search + synthesis               |
| Code       | 3       | Sandboxed code execution             |
| Documents  | 5       | PDF/report generation                |

A request using multiple capabilities costs the **sum** of their weights. For example, a request with `capabilities: ["research", "documents"]` costs 8 credits.

## Getting Credits

Every account starts with **200 free credits** (replenished monthly). When you need more, purchase credit packs:

| Pack            | Price | Per Credit |
| :-------------- | :---- | :--------- |
| 1,000 credits   | \$8   | \$0.008    |
| 5,000 credits   | \$30  | \$0.006    |
| 25,000 credits  | \$100 | \$0.004    |
| 100,000 credits | \$300 | \$0.003    |

Purchased credits **never expire**. Buy what you need, when you need it.

<Card title="Purchase credits" icon="arrow-up-right" href="https://www.stewrd.dev/pricing">
  Buy credit packs from your dashboard.
</Card>

## How Credits Are Charged

Credits are **pre-deducted** before your request is processed. If the compute service fails, credits are automatically refunded to your balance.

When your balance reaches zero, requests return a `402` status:

```json theme={null}
{
  "error": {
    "code": "insufficient_credits",
    "message": "No credits remaining. Purchase credits at https://www.stewrd.dev/pricing"
  }
}
```

## Rate Limits

All requests are rate-limited to **60 requests per minute**.

If you exceed this, you'll receive a `rate_limited` error with HTTP status 429. Wait and retry with exponential backoff.

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Limit: 60/minute."
  }
}
```

## Usage Tracking

Every response includes current usage in the `usage` object:

```json theme={null}
{
  "usage": {
    "credits_remaining": 4758,
    "credits_this_request": 3,
    "tokens_used": 847
  }
}
```

| Field                  | Description                                   |
| :--------------------- | :-------------------------------------------- |
| `credits_remaining`    | Your credit balance after this request        |
| `credits_this_request` | Credits consumed for this specific request    |
| `tokens_used`          | LLM tokens consumed for this specific request |

## Response Headers

Every response includes a credit balance header:

| Header                | Description                            |
| :-------------------- | :------------------------------------- |
| `X-Credits-Remaining` | Your credit balance after this request |

<Note>
  Free accounts receive 200 credits per month, automatically replenished. Purchased credits never expire and stack on top of any free allocation.
</Note>