Costs and caching

What each request costs

Credit is prepaid and spent per request at list price, in USD per 1,000:

Each query in a multi-query request is one search of its mode. Contents bills only the pages that were read: a URL that fails is free. usage.cost_usd in every response says what that request was billed, and GET /v1/usage returns the list in pricing. A chart costs its search per query plus the add-on (from $1.50 per 1,000 in ultra); viewing its embed, image or SVG is free, and so are GET, PATCH and DELETE on charts.

Hard caps

Set max_tokens on a request (minimum 2000) and it will never spend more. The budget is reserved before each model call; when the next call doesn’t fit, the search stops and returns everything judged so far with incomplete: true.

const res = await ts.search('el dólar', { mode: 'deep', max_tokens: 15_000 });

if (res.incomplete) {
  console.log(`Stopped at ${res.budget?.used} of ${res.budget?.max_tokens} tokens`);
}

If the cap is too small to judge even the headlines, the request fails with 402 budget_too_small before spending anything.

What you don’t pay twice

• Result cache. An identical request within 10 minutes is served from cache: cached_at says when it was computed, usage.tokens is 0, and it is not billed. Set fresh: true to skip it. The same chart request within 10 minutes returns the same chart with cached: true, also free.
• Failed requests. A request that fails on our side is not billed, and neither is a chart that found no articles on its topic (422 insufficient_data). The improvement of a chart that came back improving is free too.
• Judgment memory. What the model said about a headline for a query is remembered for a week, and the tone of an article too. A repeated search only pays for new headlines.
• Filters first. Domains, sections and dates are applied before anything is judged.
• Several queries together. Up to five queries in one request share the same model calls.

Seeing what you spend

Every search response has a usage object with the model tokens, calls, time and cost_usd of that request. GET /v1/usage returns your totals for today and the last 30 days, your limits and the price list.