---
title: "Search a live site for a topic"
method: POST
path: "/v1/search/site"
---

# Search a live site for a topic

`POST /v1/search/site`

## Request

- Base URL: `https://api.typesearch.ai`
- URL: `https://api.typesearch.ai/v1/search/site`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Can take up to a minute: returns a job (202) to poll at /v1/jobs/{id}, or server-sent events with stream: true.

## Request body

- SiteSearchRequest
  - `site` string, required: The live site to search, such as example.com.
  - `query` string, required
  - `sections` string[]: Only these sections: the section in the feed, or the start of the URL path.
  - `exclude_domains` string[]: Never these domains or paths.
  - `mode` 'ultra' | 'fast' | 'normal' | 'deep': ultra: headlines only, the cheapest · fast: headlines and standfirsts · normal: reads the best matches · deep: more headlines, the topic also in other words (synonyms and acronyms), twice the reading, snippets and the essentials of each article, and the search of the sites that cover the topic when the index falls short.
  - `max_results` integer
  - `highlights` boolean: Very short verbatim excerpts (up to 25 words, never from the first paragraph) from the articles that were read: one per article, two in deep mode. On by default only in deep mode.
  - `dedupe` boolean: Groups the same story reported by several outlets.
  - `tone` boolean: Tone toward the query: positive, neutral or negative.
  - `essential` boolean: The essentials: very short verbatim excerpts across several articles. On by default only in deep mode.
  - `questions` object: Structured output: typed questions (boolean, choice, score) that the model answers for each result.
  - `max_tokens` integer, nullable: Cap on model tokens. If it is reached, the response comes back with incomplete: true.
  - `fresh` boolean: Skips the result cache (10 minutes).
  - `temporal` 'auto' | 'off': auto: a date in the query («today», «yesterday», «tomorrow», «on September 22», «this week») is taken out of the topic, sets the publication window (unless published_after/before are given; days only bounds it) and puts the results from that day first · off: the query is taken literally.
  - `timezone` string: IANA time zone that decides what day «today» is. Defaults to Argentina (America/Argentina/Buenos_Aires).
  - `stream` boolean: Server-sent events instead of an asynchronous job.

## Response `200`

With stream: true, server-sent events.

- SearchResponse
  - `id` string, required
  - `object` 'search' | 'site_search' | 'similar', required
  - `mode` 'ultra' | 'fast' | 'normal' | 'deep', required
  - `queries` string[], required
  - `found` boolean, required
  - `total` integer, required
  - `results` object[], required
    - `url` string, required
    - `title` string, required
    - `source` string, nullable, required
    - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
    - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
    - `published_at` string, nullable, required
    - `section` string, nullable, required
    - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
    - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
    - `headline_relevance` number, required
    - `read` object, nullable, required
      - `probability` number, required
      - `centrality` number, required: 0 not mentioned · 3 main topic.
    - `highlights` string[], required
    - `tone` object, nullable, required
      - `label` 'positive' | 'neutral' | 'negative', required
      - `probabilities` object, required
      - `basis` 'article' | 'headline', required
    - `answers` object, nullable, required
      - `basis` 'article' | 'headline', required
      - `values` object, required
    - `duplicates` object[], required
      - `url` string, required
      - `title` string, required
      - `source` string, nullable, required
    - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
    - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
    - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
    - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
    - `queries` string[]: With several queries: which ones this result belongs to.
  - `groups` object[], nullable, required: With several queries: the breakdown for each one.
    - `query` string, required
    - `found` boolean, required
    - `total` integer, required
    - `results` object[], required
      - `url` string, required
      - `title` string, required
      - `source` string, nullable, required
      - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
      - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
      - `published_at` string, nullable, required
      - `section` string, nullable, required
      - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
      - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
      - `headline_relevance` number, required
      - `read` object, nullable, required
        - `probability` number, required
        - `centrality` number, required: 0 not mentioned · 3 main topic.
      - `highlights` string[], required
      - `tone` object, nullable, required
        - `label` 'positive' | 'neutral' | 'negative', required
        - `probabilities` object, required
        - `basis` 'article' | 'headline', required
      - `answers` object, nullable, required
        - `basis` 'article' | 'headline', required
        - `values` object, required
      - `duplicates` object[], required
        - `url` string, required
        - `title` string, required
        - `source` string, nullable, required
      - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
      - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
      - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
      - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
      - `queries` string[]: With several queries: which ones this result belongs to.
    - `near_misses` object[], required
      - `url` string, required
      - `title` string, required
      - `source` string, nullable, required
      - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
      - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
      - `published_at` string, nullable, required
      - `section` string, nullable, required
      - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
      - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
      - `headline_relevance` number, required
      - `read` object, nullable, required
        - `probability` number, required
        - `centrality` number, required: 0 not mentioned · 3 main topic.
      - `highlights` string[], required
      - `tone` object, nullable, required
        - `label` 'positive' | 'neutral' | 'negative', required
        - `probabilities` object, required
        - `basis` 'article' | 'headline', required
      - `answers` object, nullable, required
        - `basis` 'article' | 'headline', required
        - `values` object, required
      - `duplicates` object[], required
        - `url` string, required
        - `title` string, required
        - `source` string, nullable, required
      - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
      - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
      - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
      - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
      - `queries` string[]: With several queries: which ones this result belongs to.
    - `rejected` object[], required
      - `url` string, required
      - `title` string, required
      - `source` string, nullable, required
      - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
      - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
      - `published_at` string, nullable, required
      - `section` string, nullable, required
      - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
      - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
      - `headline_relevance` number, required
      - `read` object, nullable, required
        - `probability` number, required
        - `centrality` number, required: 0 not mentioned · 3 main topic.
      - `highlights` string[], required
      - `tone` object, nullable, required
        - `label` 'positive' | 'neutral' | 'negative', required
        - `probabilities` object, required
        - `basis` 'article' | 'headline', required
      - `answers` object, nullable, required
        - `basis` 'article' | 'headline', required
        - `values` object, required
      - `duplicates` object[], required
        - `url` string, required
        - `title` string, required
        - `source` string, nullable, required
      - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
      - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
      - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
      - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
      - `queries` string[]: With several queries: which ones this result belongs to.
    - `diffusion` object, nullable, required
      - `by_day` object[], required
        - `day` string, required
        - `count` integer, required
      - `by_source` object[], required
        - `source` string, required
        - `count` integer, required
        - `first_published_at` string, required
      - `first` object, nullable, required
        - `source` string, nullable, required
        - `url` string, required
        - `title` string, required
        - `published_at` string, required
      - `undated` integer, required
    - `tone` object, nullable, required
      - `articles` integer, required
      - `overall` object, required
        - `positive` integer, required
        - `neutral` integer, required
        - `negative` integer, required
      - `by_source` object[], required
        - `positive` integer, required
        - `neutral` integer, required
        - `negative` integer, required
        - `source` string, required
    - `essential` object, nullable, required
      - `excerpts` object[], required
        - `text` string, required
        - `url` string, required
        - `source` string, nullable, required
        - `title` string, required
    - `temporal` object, nullable, required: How the date in the query was read: the topic was judged without it, and the results from that day go first. Null when the query names none.
      - `expression` string, nullable, required: The date words in the query, such as «hoy»; null when the query asks for the latest without naming a date.
      - `from` string, nullable, required: First day of the period the query refers to (YYYY-MM-DD, in `timezone`).
      - `to` string, nullable, required: Last day of that period; the same as `from` for a single day.
      - `timezone` string, required
      - `basis` 'published' | 'event' | 'recency', required: published: what was published about that day · event: news about what is scheduled for that day (published before it) · recency: the query asks for the latest without naming a date, so the newest go first.
      - `window` object, nullable, required: The publication window the date set, when it did. Null when published_after/before (or days) in the request took precedence: then the date only sorts.
        - `from` string, required
        - `to` string, required
      - `widened` boolean, required: No result is from the requested day: they come from the days around it.
  - `near_misses` object[], required: If nothing was found: the closest matches.
    - `url` string, required
    - `title` string, required
    - `source` string, nullable, required
    - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
    - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
    - `published_at` string, nullable, required
    - `section` string, nullable, required
    - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
    - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
    - `headline_relevance` number, required
    - `read` object, nullable, required
      - `probability` number, required
      - `centrality` number, required: 0 not mentioned · 3 main topic.
    - `highlights` string[], required
    - `tone` object, nullable, required
      - `label` 'positive' | 'neutral' | 'negative', required
      - `probabilities` object, required
      - `basis` 'article' | 'headline', required
    - `answers` object, nullable, required
      - `basis` 'article' | 'headline', required
      - `values` object, required
    - `duplicates` object[], required
      - `url` string, required
      - `title` string, required
      - `source` string, nullable, required
    - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
    - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
    - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
    - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
    - `queries` string[]: With several queries: which ones this result belongs to.
  - `rejected` object[], required: The headline looked relevant, but reading the article ruled it out.
    - `url` string, required
    - `title` string, required
    - `source` string, nullable, required
    - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
    - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
    - `published_at` string, nullable, required
    - `section` string, nullable, required
    - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
    - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
    - `headline_relevance` number, required
    - `read` object, nullable, required
      - `probability` number, required
      - `centrality` number, required: 0 not mentioned · 3 main topic.
    - `highlights` string[], required
    - `tone` object, nullable, required
      - `label` 'positive' | 'neutral' | 'negative', required
      - `probabilities` object, required
      - `basis` 'article' | 'headline', required
    - `answers` object, nullable, required
      - `basis` 'article' | 'headline', required
      - `values` object, required
    - `duplicates` object[], required
      - `url` string, required
      - `title` string, required
      - `source` string, nullable, required
    - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
    - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
    - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
    - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
    - `queries` string[]: With several queries: which ones this result belongs to.
  - `diffusion` object, nullable, required
    - `by_day` object[], required
      - `day` string, required
      - `count` integer, required
    - `by_source` object[], required
      - `source` string, required
      - `count` integer, required
      - `first_published_at` string, required
    - `first` object, nullable, required
      - `source` string, nullable, required
      - `url` string, required
      - `title` string, required
      - `published_at` string, required
    - `undated` integer, required
  - `tone` object, nullable, required
    - `articles` integer, required
    - `overall` object, required
      - `positive` integer, required
      - `neutral` integer, required
      - `negative` integer, required
    - `by_source` object[], required
      - `positive` integer, required
      - `neutral` integer, required
      - `negative` integer, required
      - `source` string, required
  - `essential` object, nullable, required
    - `excerpts` object[], required
      - `text` string, required
      - `url` string, required
      - `source` string, nullable, required
      - `title` string, required
  - `reference` object, nullable, required
    - `url` string, required
    - `title` string, required
  - `custom_index` object, nullable: With `index`: the custom index that was searched.
    - `id` string, required
    - `name` string, required
  - `temporal` object, nullable, required: How the date in the query was read: the topic was judged without it, and the results from that day go first. Null when the query names none.
    - `expression` string, nullable, required: The date words in the query, such as «hoy»; null when the query asks for the latest without naming a date.
    - `from` string, nullable, required: First day of the period the query refers to (YYYY-MM-DD, in `timezone`).
    - `to` string, nullable, required: Last day of that period; the same as `from` for a single day.
    - `timezone` string, required
    - `basis` 'published' | 'event' | 'recency', required: published: what was published about that day · event: news about what is scheduled for that day (published before it) · recency: the query asks for the latest without naming a date, so the newest go first.
    - `window` object, nullable, required: The publication window the date set, when it did. Null when published_after/before (or days) in the request took precedence: then the date only sorts.
      - `from` string, required
      - `to` string, required
    - `widened` boolean, required: No result is from the requested day: they come from the days around it.
  - `site` string, nullable, required
  - `index` object, nullable, required
    - `updated_at` string, nullable, required: The oldest last refresh among the sources searched: how fresh the index was for this request.
  - `usage` object, required
    - `tokens` integer, required: Model tokens used by this request. 0 when it came from the cache.
    - `calls` integer, required
    - `cost_usd` number, nullable, required: What this request was billed, in USD: the list price of its mode (see `pricing` in GET /v1/usage), per query. 0 when it came from the cache. Null in partial results.
    - `headlines` integer, required
    - `from_memory` integer, required
    - `pages_direct` integer, required
    - `pages_browser` integer, required
    - `duration_ms` integer, required
  - `budget` object, nullable, required
    - `max_tokens` integer, required
    - `used` integer, required
    - `exhausted` boolean, required
  - `discovery` object, nullable, required: Discovery: when the index has fewer than 3 good matches, typesearch looks for sources beyond it and reads them at the original site. Null only in partial events, while it is still running.
    - `status` 'used' | 'background' | 'skipped' | 'budget' | 'timeout', required: 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 does not apply · budget: the discovery limit was reached · timeout: the time budget ran out (incomplete: true).
    - `sites` integer, required: Sites beyond the index that contributed candidates.
    - `ms` integer, required: Time it added to this request, in milliseconds.
  - `incomplete` boolean, required: The token cap (max_tokens) or the discovery time budget ran out: there may be more.
  - `cached_at` string, nullable, required
  - `warnings` object[], required
    - `code` string, required
    - `message` string, required

## Other responses

- `202`: The job that was created.
- `402`: Payment required: `insufficient_credits` (no credit left), `spend_limit_reached` (the key hit its monthly limit) or `budget_too_small`.
- `default`: Error (RFC 9457). In English unless the request sends `Accept-Language: es`.

---

[API](https://skmtc.dev/typesearch/apis/typesearch-news-search-api.md) · [All operations](https://skmtc.dev/typesearch/apis/typesearch-news-search-api/llms.txt) · [OpenAPI document](https://skmtc.dev/typesearch/apis/typesearch-news-search-api/revisions/b270b9a9c6a5?raw)