Search

POSThttps://api.typesearch.ai/v1/search

Searches the index and returns the relevant articles, most relevant first, each with a calibrated score. With several queries, results come merged and each query also gets its own entry in groups.

Set stream: true to receive Server-Sent Events while it searches.

Body

querystring | string[]required
One query, or up to five judged together in the same request, which is cheaper than searching them one by one. 2–200 characters each.
Items: up to 5
sourcesenum<string>[]
Only these index sources. Use the ids from GET /v1/sources.
One of: lanacion · infobae · cronista · ambito · pagina12 · lavoz · perfil · minutouno · losandes
include_domainsstring[]
Only these domains or paths, up to 20. A domain includes its subdomains; a path such as infobae.com/economia includes everything under it.
Items: up to 20
exclude_domainsstring[]
Never these domains or paths, up to 20. Same matching rules as include_domains.
Items: up to 20
sectionsstring[]
Only these sections: the section the source declares, or the first segment of the path (economia).
Items: up to 20
daysinteger | null
The last N days, 1–365. null searches the whole index. Defaults to 7, unless published_after or published_before is set.
Range: 1–365
published_afterdate | date-time
Published on or after this moment. A bare date (2026-09-20) covers the whole day in UTC−3; a date-time needs an offset.
published_beforedate | date-time
Published on or before this moment, inclusive. Same format as published_after.
modeenum<string>Default: "normal"
ultra judges headlines only and is the cheapest · fast judges headlines and standfirsts · normal also reads the top results to confirm them · deep judges the whole index and reads more.
max_resultsintegerDefault: 10
How many results to return, 1–50.
Range: 1–50
highlightsboolean
Return verbatim excerpts (up to 280 characters) from the articles that were read. Defaults to true in deep and false otherwise.
dedupebooleanDefault: false
Collapse the same story told by several outlets into a single result, listing the others in duplicates.
tonebooleanDefault: false
Classify each result as positive, neutral or negative relative to the query, and summarise it by source.
essentialboolean
Return up to three verbatim excerpts from different sources that capture the story. Defaults to true in deep.
questionsmap<string, …>
Structured output: up to 8 typed questions (boolean, choice or score) answered on every result, keyed by a name you choose.
max_tokensinteger | null
A hard cap on model tokens for this request, minimum 2000. If it is reached, you get everything judged so far with incomplete: true.
Range: 2000–9007199254740991
freshbooleanDefault: false
Skip the result cache. Otherwise, an identical request within 10 minutes is served from cache at no cost.
streambooleanDefault: false
Send Server-Sent Events while searching: step, partial and a final result.

Response

idstring
The request id, also sent in the X-Request-Id header.
objectenum<string>
search, site_search or similar.
modeenum<string>
The mode that was used.
One of: ultra · fast · normal · deep
queriesstring[]
The queries that were searched.
foundboolean
Whether any article reached the relevance threshold (a score of 0.5).
totalinteger
How many relevant articles were found. It can exceed the number of results returned.
Range: -9007199254740991–9007199254740991
resultsobject[]
The results, most relevant first.
Show child attributes
- urlstring
  The article’s canonical URL.
- titlestring
  The headline.
- sourcestring | null
  The publication.
- published_atstring | null
  Publication time, ISO 8601 in UTC.
- sectionstring | null
  The section, when the source provides one.
- snippetstring | null
  The standfirst or description, as published.
- scorenumber
  Calibrated probability (0–1) that the article is about the query: from the article when it was read, from the headline otherwise. Between 0.35 and 0.65 the model is undecided.
- headline_relevancenumber
  The probability judged from the headline alone.
- readobject | null
  Present when the article was opened and read to confirm it.
  Show child attributes
  - probabilitynumber
    The probability after reading the article.
  - centralitynumber
    How central the query is to the article, from 0 (not present) to 3 (the main topic).
- highlightsstring[]
  Verbatim excerpts about the query, up to 280 characters each.
- toneobject | null
  Present when tone was requested.
  Show child attributes
  - labelenum<string>
    positive, neutral or negative, relative to the query.
  - probabilitiesmap<string, number>
    The probability of each label.
  - basisenum<string>
    article when judged on the text, headline otherwise.
- answersobject | null
  Present when questions were sent.
  Show child attributes
  - basisenum<string>
    article when answered on the text, headline otherwise.
  - valuesmap<string, …>
    One answer per question key: probability for boolean, choice for choice and score for score, with probabilities and confidence where they apply.
- duplicatesobject[]
  With dedupe: other outlets that told the same story.
  Show child attributes
  - urlstring
    The duplicate’s URL.
  - titlestring
    The duplicate’s headline.
  - sourcestring | null
    The duplicate’s publication.
- found_inenum<string>
  Where it was found: index, or on a live site homepage, section or site_search.
- queriesstring[]
  With several queries: which ones this result answers.
groupsobject[] | null
With several queries: one entry per query, with its own results and enrichments.
Show child attributes
- querystring
  The query.
- foundboolean
  Whether this query found anything.
- totalinteger
  Relevant articles found for this query.
  Range: -9007199254740991–9007199254740991
- resultsobject[]
  Results for this query.
  Same fields as results
- near_missesobject[]
  When nothing was found: what came closest, so your agent can decide.
  Same fields as results
- rejectedobject[]
  Articles whose headline looked relevant but scored below 0.6 once read.
  Same fields as results
- diffusionobject | null
  How the story spread: articles per day and per source, and who published first. Computed from the index at no extra cost.
  Same fields as diffusion
- toneobject | null
  With tone: counts by label, overall and per source.
  Same fields as tone
- essentialobject | null
  With essential: up to three verbatim excerpts from different sources.
  Same fields as essential
near_missesobject[]
When nothing was found: what came closest, so your agent can decide.
Same fields as results
rejectedobject[]
Articles whose headline looked relevant but scored below 0.6 once read.
Same fields as results
diffusionobject | null
How the story spread: articles per day and per source, and who published first. Computed from the index at no extra cost.
Show child attributes
- by_dayobject[]
  Articles per day, in UTC−3.
  Show child attributes
  - daystring
    The day, YYYY-MM-DD.
  - countinteger
    Articles that day.
    Range: -9007199254740991–9007199254740991
- by_sourceobject[]
  Articles per source, with the time of each source’s first article.
  Show child attributes
  - sourcestring
    The publication.
  - countinteger
    Its articles.
    Range: -9007199254740991–9007199254740991
  - first_published_atstring
    When it first published.
- firstobject | null
  The first article published.
  Show child attributes
  - sourcestring | null
    Its publication.
  - urlstring
    Its URL.
  - titlestring
    Its headline.
  - published_atstring
    When it was published.
- undatedinteger
  Articles without a publication date.
  Range: -9007199254740991–9007199254740991
toneobject | null
With tone: counts by label, overall and per source.
Show child attributes
- articlesinteger
  Articles classified.
  Range: -9007199254740991–9007199254740991
- overallobject
  Counts by label.
  Show child attributes
  - positiveinteger
    Positive articles.
    Range: -9007199254740991–9007199254740991
  - neutralinteger
    Neutral articles.
    Range: -9007199254740991–9007199254740991
  - negativeinteger
    Negative articles.
    Range: -9007199254740991–9007199254740991
- by_sourceobject[]
  Counts by label, per source.
  Show child attributes
  - positiveinteger
    Positive articles.
    Range: -9007199254740991–9007199254740991
  - neutralinteger
    Neutral articles.
    Range: -9007199254740991–9007199254740991
  - negativeinteger
    Negative articles.
    Range: -9007199254740991–9007199254740991
  - sourcestring
    The publication.
essentialobject | null
With essential: up to three verbatim excerpts from different sources.
Show child attributes
- excerptsobject[]
  The excerpts.
  Show child attributes
  - textstring
    The excerpt, verbatim.
  - urlstring
    The article it comes from.
  - sourcestring | null
    Its publication.
  - titlestring
    Its headline.
referenceobject | null
On similar: the reference article.
Show child attributes
- urlstring
  Its URL.
- titlestring
  Its headline.
sitestring | null
On site_search: the site that was searched.
indexobject | null
On index searches: the state of the index at the time of the search.
Show child attributes
- sourcesinteger
  Sources consulted.
  Range: -9007199254740991–9007199254740991
- articlesinteger
  Articles considered.
  Range: -9007199254740991–9007199254740991
- updated_atstring | null
  The last time a source was refreshed.
- sources_without_articlesstring[]
  Sources that returned no articles for the period.
usageobject
What the request consumed.
Show child attributes
- tokensinteger
  Model tokens. 0 when served from cache.
  Range: -9007199254740991–9007199254740991
- callsinteger
  Model calls.
  Range: -9007199254740991–9007199254740991
- cost_usdnumber | null
  Cost in US dollars, when known.
- headlinesinteger
  Headlines considered, including those judged before.
  Range: -9007199254740991–9007199254740991
- from_memoryinteger
  Of those, the ones judged before and reused at no cost.
  Range: -9007199254740991–9007199254740991
- pages_directinteger
  Articles read with a plain request.
  Range: -9007199254740991–9007199254740991
- pages_browserinteger
  Pages opened with a browser.
  Range: -9007199254740991–9007199254740991
- duration_msinteger
  Time on the server, in milliseconds.
  Range: -9007199254740991–9007199254740991
budgetobject | null
With max_tokens: the cap, how much was used and whether it was reached.
Show child attributes
- max_tokensinteger
  The cap you set.
  Range: -9007199254740991–9007199254740991
- usedinteger
  Tokens used.
  Range: -9007199254740991–9007199254740991
- exhaustedboolean
  Whether the cap was reached.
incompleteboolean
true when max_tokens was reached before everything was judged.
cached_atstring | null
When served from cache: when the result was computed.
warningsobject[]
Non-fatal notes about the request, such as a domain that is not in the index.
Show child attributes
- codestring
  A stable code.
- messagestring
  A human-readable explanation.

import Typesearch from 'typesearch-js';

const ts = new Typesearch();

const res = await ts.search('el dólar', {
  mode: 'normal',
  max_results: 10,
  include_domains: ['infobae.com', 'lanacion.com.ar'],
  published_after: '2026-09-20',
  tone: true,
});

200 OK

{
  "id": "req_8fKq2mZr1xYt",
  "object": "search",
  "mode": "normal",
  "queries": ["el dólar"],
  "found": true,
  "total": 14,
  "results": [
    {
      "url": "https://www.infobae.com/economia/…",
      "title": "El dólar oficial cerró estable en una rueda con poco volumen",
      "source": "Infobae",
      "published_at": "2026-09-21T18:05:00.000Z",
      "section": "economia",
      "snippet": "La divisa se mantuvo sin cambios frente al cierre anterior.",
      "score": 0.96,
      "headline_relevance": 0.91,
      "read": { "probability": 0.96, "centrality": 3 },
      "highlights": ["El dólar mayorista terminó la jornada sin variaciones…"],
      "tone": {
        "label": "neutral",
        "probabilities": { "positive": 0.08, "neutral": 0.86, "negative": 0.06 },
        "basis": "article"
      },
      "answers": null,
      "duplicates": [],
      "found_in": "index"
    }
  ],
  "groups": null,
  "near_misses": [],
  "rejected": [],
  "tone": {
    "articles": 14,
    "overall": { "positive": 2, "neutral": 10, "negative": 2 },
    "by_source": []
  },
  "usage": { "tokens": 4210, "calls": 4, "cost_usd": 0.001, "duration_ms": 2380 },
  "incomplete": false,
  "cached_at": null,
  "warnings": []
}