Costs and caching

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.
• 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 and time of that request. GET /v1/usage returns your totals for today and the last 30 days, and your limits.