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, faster than searching them one by one; each one is billed as a search of its mode. 2–200 characters each.
Items: up to 5
indexstring
Search your own custom index (idx_…) instead of the news index: the same modes, prices, questions, tone and highlights. One query per request, and no date filter unless you set one. See the Custom index guide.
sourcesstring[]
Only these sources, by domain (such as diarioejemplo.example), up to 100. A domain that is not in the index comes back as a domain_not_indexed warning.
Items: up to 100
include_domainsstring[]
Only these domains or paths, up to 20. A domain includes its subdomains; a path such as diarioejemplo.example/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
countriesstring[]
Only sources based in these countries: ISO 3166-1 alpha-2 codes, such as AR or US.
Items: up to 50
languagesstring[]
Only sources that publish in these languages: ISO 639-1 codes, such as es or en. A tag such as pt-BR counts as pt.
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 a short verbatim excerpt from the articles that were read: at most one per article (two in deep), up to 25 words, never from the first paragraph. 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, with the same limits as highlights. 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.
temporalenum<string>Default: "auto"
One of: auto · off
timezonestring
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, up to 240 characters.
- sourcestring | null
  The publication.
- countrystring | null
- languagestring | null
- published_atstring | null
  Publication time, ISO 8601 in UTC.
- sectionstring | null
  The section, when the source provides one.
- snippetstring | null
  The description the publisher gives the article in its feed or page metadata, up to 300 characters.
- 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: at most one per article (two in deep), up to 25 words, never from the first paragraph. None for short articles.
- 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.
- date_matchenum<string> | null
  One of: exact · adjacent · unknown · outside
- referenced_datestring | null
- found_inenum<string>
  Where it was found: index, custom_index when you searched your own index, or on a live site homepage, section or site_search.
  One of: index · homepage · section · site_search · discovery · custom_index
- datamap<string, string | number> | null
  On custom index searches: the structured data the page declares, such as price, currency, availability, brand or sku. null when it declares none.
- 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
- temporalobject | null
  Same fields as temporal
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.
custom_indexobject | null
With index: the custom index that was searched.
Show child attributes
- idstring
  Its id, idx_….
- namestring
  The name you gave it.
temporalobject | null
Show child attributes
- expressionstring | null
- fromstring | null
- tostring | null
- timezonestring
- basisenum<string>
  One of: published · event · recency
- windowobject | null
  Show child attributes
  - fromstring
  - tostring
- widenedboolean
sitestring | null
On site_search: the site that was searched.
indexobject | null
On index searches: how fresh the index was at the time of the search.
Show child attributes
- updated_atstring | null
  The last time a source was refreshed.
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.
discoveryobject | null
Discovery: when the index has fewer than 3 good matches, we look for sources beyond it and read them at the original site. null only in partial events, while it’s still running.
Show child attributes
- statusenum<string>
  used: it searched beyond the index within the time budget · background: in ultra or fast there was nothing to check quickly; it keeps learning in the background · skipped: the index had enough, or it doesn’t apply · budget: the discovery limit was reached · timeout: the time budget ran out (incomplete: true).
- sitesinteger
  Sites beyond the index that contributed candidates.
  Range: -9007199254740991–9007199254740991
- msinteger
  Time it added to this request, in milliseconds.
  Range: -9007199254740991–9007199254740991
incompleteboolean
true when max_tokens or the discovery time budget ran out before everything was judged: there may be more.
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: ['reddiaria.example', 'diarioejemplo.example'],
  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://reddiaria.example/economia/…",
      "title": "El dólar oficial cerró estable en una rueda con poco volumen",
      "source": "Red Diaria",
      "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.0022, "duration_ms": 2380 },
  "incomplete": false,
  "cached_at": null,
  "warnings": []
}