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

# Usage & Credits

> How usage is measured, what operations consume it, and how to check your balance.

## How usage is measured

Every call to Alchemist is attributed to your API key and broken down into two layers:

| Layer            | What it tracks                                                 |
| ---------------- | -------------------------------------------------------------- |
| **Requests**     | Top-level actions: a search, a document fetch, a chat turn     |
| **Token events** | The underlying LLM and embedding calls that power each request |

You're billed at the request level — not per token. Tokens are tracked internally for cost transparency and displayed in your usage dashboard.

## What counts as a request

| Operation         | Triggered by                                                     |
| ----------------- | ---------------------------------------------------------------- |
| `search`          | `POST /api/insights/search` or `search_insights` MCP tool        |
| `explore_message` | Chat turns in the Alchemist console or `search_web` MCP fallback |

Fetching documents (`GET /api/documents`, `GET /api/documents/{id}`) does not currently count against your search quota.

## Checking your usage

### Via the API

```bash theme={null}
curl "https://api.askalchemist.com/console/content/me/usage?days=30" \
  -H "Authorization: Bearer <clerk_jwt>"
```

```json theme={null}
{
  "days": 30,
  "start_date": "2026-05-17",
  "end_date": "2026-06-16",
  "total_input_tokens": 124800,
  "total_output_tokens": 38200,
  "total_tokens": 163000,
  "total_requests": 412,
  "daily": [
    {
      "date": "2026-06-16",
      "input_tokens": 3200,
      "output_tokens": 980,
      "total_tokens": 4180,
      "request_count": 11
    }
  ],
  "operations": [
    {
      "operation": "search",
      "input_tokens": 98000,
      "output_tokens": 12000,
      "total_tokens": 110000,
      "request_count": 380
    }
  ]
}
```

### Via the app

Go to **[app.askalchemist.com/settings/usage](https://app.askalchemist.com/settings/usage)** for a visual breakdown by day and operation type.

## Free tier limits

The free tier includes a generous monthly allowance for building and testing.

<Note>
  Specific free-tier limits are shown in the app under **Settings → Usage**. Contact [hello@askalchemist.com](mailto:hello@askalchemist.com) for higher limits or custom plans.
</Note>

## Rate limits

Requests are rate-limited per API key, not per account. See the [API Keys page](/authentication) for current limits and rate limit headers.

## Cost-free operations

The following operations are tracked but do not consume your search quota:

* `GET /api/documents/filters` — listing available sources
* `GET /api/documents` — browsing document metadata
* `GET /api/documents/{doc_id}` — fetching a document and its insights
* `list_filter_options` MCP tool
* `list_documents` MCP tool
* `get_document` MCP tool