Search the index
Queries, filters, and how to read every result.
POST /v1/search searches the index and returns the relevant articles, most relevant first.
const res = await ts.search('Boca Juniors', {
mode: 'fast',
max_results: 10,
include_domains: ['infobae.com/deportes', 'lanacion.com.ar'],
days: 3,
});Writing a query
A query is a topic, not a question: el dólar, Boca Juniors, la visita del papa. Between 2 and 200
characters.
For the best recall, write it the way the coverage you are after would phrase it — in Spanish for the Argentine press, with the name the headlines use. Acronyms and paraphrases are found less often than the name itself.
Filters
Filters are applied before anything is judged, so what you filter out costs nothing.
| Filter | Example | Notes |
|---|---|---|
include_domains | ["lanacion.com.ar", "infobae.com/economia"] | A domain includes its subdomains; a path, everything under it. Up to 20. |
exclude_domains | ["perfil.com"] | Same rules. |
sections | ["economia", "politica"] | The section the source declares, or the first segment of the path. |
days | 3 | The last N days. null searches the whole index. Defaults to 7. |
published_after, published_before | "2026-09-20" | A bare date covers the whole day; a date-time needs an offset. |
sources | ["lanacion", "infobae"] | Ids from GET /v1/sources. |
A domain that is not in the index comes back as a domain_not_indexed entry in warnings, not as an
error.
Reading the results
Each result has a score: the calibrated probability that the article is about your query. It
comes from the article when it was read (read is set), and from the headline otherwise. Results are
the articles scored 0.5 or more:
score | What it means |
|---|---|
| 0.65 – 1 | Relevant. |
| 0.5 – 0.65 | Undecided. Returned, but the model is not sure — don’t treat 0.56 as a weak yes. |
Calibrated means you can threshold on it: across many results scored 0.9, about nine in ten are
relevant. When your agent needs certainty, keep results above 0.8, or use normal mode so the top ones
are read before they are ranked.
Besides results, the response tells you what happened on the edges:
rejected— articles whose headline looked relevant but scored below0.6once read.near_misses— when nothing reaches0.5, what came closest (from0.15), so your agent can decide whether to broaden the query.total— how many relevant articles exist, which can be more thanmax_results.
Highlights
In normal and deep, set highlights: true to get up to two verbatim excerpts per read article, up to
280 characters each — the paragraphs that are about your query. They are quoted, never rewritten.
const res = await ts.search('el Presupuesto 2027', { mode: 'normal', highlights: true });
console.log(res.results[0]?.highlights);