Skip to main content
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.
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. 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.