Search a live site

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

Reads the site live: its homepage first and, when that is not enough, the sections most likely to cover the topic and the site’s own search box, in parallel. It can take up to a minute, so it responds 202 Accepted with a job and a Location header.

With stream: true it responds with Server-Sent Events instead.

Body

sitestringrequired
The live site to search: a domain such as diarioejemplo.example, or a URL.
querystringrequired
What to look for on the site. 2–200 characters.
sectionsstring[]
Only these sections: the section the source declares, or the first segment of the path (economia).
Items: up to 20
exclude_domainsstring[]
Never these domains or paths, up to 20. Same matching rules as include_domains.
Items: up to 20
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 instead of creating a job.

Response

202 Accepted with a job. See GET /v1/jobs/{id} for its fields.

import Typesearch from 'typesearch-js';

const ts = new Typesearch();

// Create the job and wait for it
const res = await ts.siteSearchAndWait('diarioejemplo.example', 'el dólar', {
  mode: 'normal',
  max_results: 10,
});

202 Accepted

{
  "id": "job_Qm3sV9aLp2Rt",
  "object": "job",
  "status": "queued",
  "created_at": "2026-09-22T14:03:11.000Z",
  "finished_at": null,
  "result": null,
  "error": null
}