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

> ## Agent Instructions
> getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean.
> Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else.
> The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it.
> The product's name is written getclean, in lower case.

# Set a spending limit that no call can pass

> Set the most that one call can cost with max_cost. The call does what fits under the limit, says what it left out, and never spends more. A key and a run can have budgets of their own.

An agent that runs alone at night needs a hard limit on what it can spend, and the price of some calls is not known before they run: a document's page count is known only after it is downloaded. `max_cost` sets the most that one call can cost. It is set before the work, and no call spends more.

## Set the limit of one call

Send `max_cost` with an amount and the currency of your account.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "SOURCE_URL",
    "max_cost": { "amount": "1.00", "currency": "USD" }
  }'
```

```python Python theme={"theme":"css-variables"}
from getclean import GetClean, Money

client = GetClean()

record = client.fetch_contents(
    url="SOURCE_URL",
    max_cost=Money(amount="1.00", currency="USD"),
)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { GetClean } from "getclean";

const client = new GetClean();

const record = await client.fetchContents({
    url: "SOURCE_URL",
    max_cost: { amount: "1.00", currency: "USD" },
});
```

Replace `SOURCE_URL` with the address of a page or a document.

A call without `max_cost` has the limit that the key sets for one call.

## Know which limit applies

Up to 5 limits apply to a call, and the lowest one decides.

| Limit | Who sets it |
| - | - |
| `max_cost` | You, in the request. |
| The key's limit for one call | The owner of the account. |
| The run's budget | The owner of the account. |
| The key's budget for a period | The owner of the account. |
| The balance | The funds of the account. |

`cost.ceiling` in a response has the limit that applied. `get_limits` returns the limits of your key and the balance.

## Know what is left out first

If the limit cannot cover everything a request asks for, the call does the most important work first and leaves out the extras, each with a notice that names it.

In a fetch, the read of the page or of the document's pages comes first. Then come the filled schema, the highlights, the summary, and the picture, and they are left out from the end of that list. If the limit stops the pages of a document, the record has the pages read so far, with the outcome `partial` and the reason `cost_capped`.

In a search, the extras of the fetches go first, then whole fetches, then the ranking, then the choice of datasources, and last the number of results taken from each datasource.

Nothing is left out without a notice. Each cut has the notice `cost_cut`, or `budget_cut` if a budget made it.

## Learn the size of a document before you pay for it

Fetch the address with `max_characters` set to `0` and a low `max_cost`. The response has the number of pages and the outline, for the cost of one fetch, and no page is read. You can then set a limit that fits, or read only the sections you need.

## Send a request again without paying twice

A call that can be charged takes an idempotency key in the header `Idempotency-Key`. A request that is sent again with the same key and the same body returns the first response, with `replayed` set to `true`, and is not charged again. The SDKs make a key for each call and use it for every retry. Uploads and batches must have a key, because a repeat of them costs the most.

## Act on a refusal about money

A `max_cost` that is lower than the smallest call is refused with the problem `cost-exceeds-cap`, and `minimum_cap` in the problem has the least amount that would run the call.

If the balance or a budget is used up, the problem is `credit-exhausted`, `run-budget-exhausted`, or `key-budget-exhausted`. Only the owner of the account can fix these, so an agent should stop and report the problem's `amount_needed`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.