Search filters

These options narrow and reorder what a search returns. They work on /v1/search, /v1/news, /v1/images and /v1/videos as listed below, cost nothing extra, and every other endpoint rejects them with 400 invalid_request.

curl https://api.serpkite.com/v1/search \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"rust async runtime","include_domains":["github.com","docs.rs"],"exclude_domains":["reddit.com"],"start_date":"2026-01-01"}'

Domain filters

Each list takes up to 20 entries, as a JSON array or a comma-separated string:

• include_domains and exclude_domains are compiled into Google operators (q (site:a OR site:b) -site:c) and then enforced on the returned rows, because a fallback engine may treat site: as a hint. Rows that don’t match are dropped and position is renumbered. A page where nothing matches is an empty result and is not billed.
• q plus the compiled operators must stay within 2,048 characters.
• They can’t be combined with engine: "consensus".
• boost_domains (search and news) filters nothing: matching rows move to the top, and both groups keep their original order.
• request echoes the caller’s q and the normalised lists, never the compiled operators.

Date range

start_date and end_date (YYYY-MM-DD, either or both) become Google’s custom date range (tbs=cdr:1,cd_min:…,cd_max:…). They can’t be combined with time or tbs. When a request falls back to another engine (engine), the range goes along; an engine that can’t filter by date is skipped rather than answering unfiltered.

Typed dates: published_at

Organic results, news, top stories and videos carry Google’s date as shown (“3 days ago”, “Mar 3, 2026”). When it parses, SerpKite adds published_at in ISO 8601: a date (2026-09-30) for absolute and day-level relative dates, a UTC time (2026-10-03T09:00:00Z) for “2 hours ago”. Relative dates are resolved against the time the page was fetched, so cached results keep the right date.

Highlights

With include_content on /v1/search, highlights: true returns up to 3 passages of about 600 characters per fetched page in results[].highlights instead of the whole page in content. Passages are split along the page’s headings and ranked against q with BM25 (a lexical ranker: deterministic, no model involved). Each one has text, score (higher is better, comparable within one response) and heading, the section path it sits under.

{
  "position": 1,
  "title": "Async in depth",
  "link": "https://docs.example.org/async",
  "domain": "docs.example.org",
  "published_at": "2026-09-30",
  "highlights": [
    { "text": "An async runtime drives futures to completion by polling them…", "score": 7.412, "heading": "Async in depth > Runtimes" }
  ]
}

Highlights cost nothing on top of include_content (+1 credit per fetched page). In format: "markdown" each passage is wrapped in a highlight tag under its result; format: "compact" lists the passage texts.

Choose the matching workflow

Use filters and highlights in a RAG pipeline to focus the evidence you retrieve. /v1/rank rejects domain filters, boosts and highlights because they would change the positions being measured. Search and news monitors save domain includes/excludes and time, but do not accept absolute date ranges, boosts or highlights.

Related: Common parameters, Page content, Search providers.