# Credits and limits

> What each call costs, how a search is reserved and reconciled, what the rate limits are, and how to check a balance before a long run.

Canonical page: https://www.refolk.ai/developers/credits-and-limits



Credits are the meter, and they are the same credits the app spends. There is
no separate API plan and no per-seat pricing: whatever the account is on, the
API spends the same balance the interface does. A new account starts with
500 credits, and the free tier tops back up to 250
each month. A paid plan tops up to its own allowance instead - call
`/v1/credits` and read `monthlyFloor` rather than assuming a number.

## What each call costs

| Call | Cost |
| --- | --- |
| Search in plain English | Reserves 10, reconciled against actual spend |
| Search with filters | 1 credit, whatever the page size |
| Turn a sentence into a filter set | 1 credit |
| Balance and identity | Free |

Every metered response carries a `credits` object with what the call charged
and what is left, so a client that tracks spend never has to ask a second
endpoint.

```json
{ "credits": { "charged": 6, "balance": 494 } }
```

## Why a search reserves more than it costs

An agentic search does not know what it will cost until it has run: a simple
question is answered in one pass, a hard one reads six sources. Charging
afterwards would mean anyone could start any number of searches on an empty
balance. So the reservation is taken first, at a size that covers a heavy run,
and the unused part comes straight back when the run settles.

You are charged for the search you got, never for the one it might have been.

## What gets refunded

- A filtered search that fails upstream is refunded in full. So is a
  translation that fails.
- An agentic search that ends in an error having produced no people, companies,
  or repositories is refunded in full. One that produced results and then
  failed is charged for what it did.
- A request refused for want of credits, a bad key, or a malformed body is
  never charged, because nothing ran.

## Checking before a long run

Free to call, so a batch job that checks first can stop cleanly rather than
failing partway through on a `402`.

### `GET /api/v1/credits`

The balance, the monthly floor, and what each kind of call costs.

**Cost:** free

**curl**

```bash
curl https://www.refolk.ai/api/v1/credits \
  -H "Authorization: Bearer $REFOLK_API_KEY"
```

**Response**

```text
{
  "balance": 494,
  "purchased": 0,
  "planCredits": 494,
  "plan": { "id": "free", "name": "Free" },
  "monthlyFloor": 250,
  "costs": {
    "agenticSearchReservation": 10,
    "structuredSearch": 1,
    "translate": 1
  }
}
```

**Response**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `balance` | `number` | required | What is left to spend, across both buckets. |
| `purchased` | `number` | required | Bought credits. These survive a refill and are never taken away. |
| `planCredits` | `number` | required | The allowance slice. This is what gets topped up, and it does not roll over. |
| `plan` | `object` | required | `id` and `name` of the account's plan. |
| `monthlyFloor` | `number` | required | What the allowance refills to at the start of each period. Depends on the plan. |
| `costs` | `object` | required | What each kind of call costs right now. |

Run this request in the playground: https://www.refolk.ai/developers/playground?endpoint=credits. Free. Nothing is charged for this one.

```json
{}
```

## Rate limits

Per key, not per account, so one runaway script cannot take the rest of your
integrations down with it.

| Class | Burst | Refill |
| --- | --- | --- |
| Searches | 20 | one every 2 seconds |
| Balance and identity reads | 60 | two a second |
| Concurrent agentic searches | 2 | n/a |

A third concurrent search gets a `429` rather than a queue, because a queue on
a ninety-second call is a timeout with extra steps.

> **Retry-After means what it says**
>
> A `429` carries a `Retry-After` header and the same number in
> `error.retryAfter`. The limit is a token bucket, so waiting works and an
> early retry spends the budget it was waiting for.

## Topping up

From [settings](/hire/settings), the same as the app. See
[pricing](/pricing) for what a pack costs. An account can never be
overdrafted: a call that would take the balance below zero is refused before it
runs.



---

## More of the API documentation

- [Quickstart](https://www.refolk.ai/developers/quickstart.md): Create a key, run your first search, and read what comes back. A working request in under two minutes, in curl, TypeScript, and Python.
- [Authentication](https://www.refolk.ai/developers/authentication.md): How API keys work: creating one, sending it, rotating it, and what happens when one leaks. Keys are shown once and hashed at rest.
- [Playground](https://www.refolk.ai/developers/playground.md): Run any endpoint from the browser, signed in, on your own credits. Prefilled examples, the real response, and the equivalent curl for your own code.
- [Search in plain English](https://www.refolk.ai/developers/agentic-search.md): POST /v1/search. One sentence in, a ranked shortlist out, with the evidence behind every pick. Blocking or streamed as server-sent events.
- [Search with filters](https://www.refolk.ai/developers/structured-search.md): POST /v1/people/search. An exact filter set in, a deterministic page of people out, one credit a call. Every field, every allowed value, and how to paginate.
- [Errors](https://www.refolk.ai/developers/errors.md): One error shape for every endpoint, a closed set of types, and which of them are worth retrying. What gets refunded when a call fails.
- [MCP server](https://www.refolk.ai/developers/mcp.md): Give Claude, Cursor, VS Code, or any MCP client the ability to search for people mid-conversation. One URL, one header, four tools.
- [OpenAPI document](https://www.refolk.ai/api/v1/openapi.json): the machine-readable specification.

Authenticate with `Authorization: Bearer rfk_live_...`. Keys are created at https://www.refolk.ai/hire/api.