Search

Search the web, news or images and get ranked results. Optionally read the top results and get the passages that answer your query, scrape them in any format, or have a short cited answer written from them. Use Search when you want results to choose from; use Research when you want a finished answer with verified citations.

Requires an API key with the search scope. New keys get crawl and scrape by default, so add search when you create the key. Search is synchronous: the search and any page reads share a 25-second budget, and include_answer gets 30 more seconds to write.

curl -X POST "https://xdive.dev/api/orgs/$ORG_ID/search" \
  -H "X-API-Key: $XDIVE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "query": "rotate API keys without downtime",
    "limit": 5,
    "freshness": "py",
    "search_depth": "advanced"
  }'

from xdive import XDive
 
xdive = XDive()  # reads XDIVE_API_KEY
response = xdive.search(
    "rotate API keys without downtime",
    limit=5,
    freshness="py",
    search_depth="advanced",
)
for result in response["results"]:
    best = result.get("passages", [{}])[0].get("text", "")
    print(result["rank"], result["url"], best[:120])

import { XDive } from "xdive";
 
const xdive = new XDive(); // reads XDIVE_API_KEY
const response = await xdive.search("rotate API keys without downtime", {
  limit: 5,
  freshness: "py",
  search_depth: "advanced",
});
for (const result of response.results) {
  console.log(result.rank, result.url, result.passages?.[0]?.text.slice(0, 120));
}

Parameters

Freshness

Domain filters

Entries are host names such as example.com, without a scheme, path or port. A filter matches the host and its subdomains: example.com matches docs.example.com but not notexample.com. Filters are applied after the engine ranks results, so a narrow include_domains can return fewer than limit results.

Search depth

With search_depth: "advanced", the top 8 web and news results are read in parallel, through the page cache, within 6 seconds. Each result that could be read gains:

• page: the page's url, title and main-content markdown, so you need no second fetch;
• passages: up to 3 excerpts most relevant to the query, best first;
• relevance_score: the score of the best passage.

Results keep the search engine's order. Advanced search does not re-rank them by relevance_score; sort by it yourself if that suits your use. Results that could not be read in time have no passages. Each page read counts as one page against your quota.

Passage scores are BM25 relevance scores of the passage against the query: higher is more relevant, and 0 means no query term in common, so such passages are left out.

Auto parameters

auto_parameters: true fills in parameters you left unset from the query's wording. Words such as "news", "latest", "breaking", "today" or "announced" add news to sources. "today", "yesterday", "breaking", "right now", "this week" or "latest" set freshness to pw; "this month", "recent" or "recently" set pm; the current year written in the query sets py. The parameters used are returned in parameters.

Scraping results

scrape fetches the top web and news results through the scrape pipeline and attaches each one as page, with passages and relevance_score computed from its content.

A result that could not be scraped has scrape_error instead of page. With advanced and Markdown-only scraping, pages already read are reused; with other formats they are fetched again, but a page is never counted twice.

Answer

include_answer: true writes an answer of at most about 150 words from the top results, citing them as [1], [2]. Citation numbers are checked against the sources in code, so the answer cannot cite a page that was not read. If you do not pass scrape, the top 5 results are scraped for it.

The answer needs an LLM configured for your organization. Problems with the answer never fail the search: answer then holds an error instead.

Response

{
  "query": "rotate API keys without downtime",
  "provider": "brave",
  "search_depth": "advanced",
  "results": [
    {
      "id": "4f9c2a7e1b3d5f80",
      "source": "web",
      "rank": 1,
      "title": "Rotating API keys safely",
      "url": "https://docs.example.com/security/key-rotation",
      "description": "Issue a second key, deploy it, then revoke the first.",
      "published_at": "2026-03-02T00:00:00Z",
      "page": {
        "url": "https://docs.example.com/security/key-rotation",
        "title": "Rotating API keys safely",
        "depth": 0,
        "markdown": "# Rotating API keys safely\n\nKeep two keys active during a rotation..."
      },
      "passages": [
        {
          "text": "Keep two keys active during a rotation. Issue the new key, roll it out to every client, confirm traffic has moved, then revoke the old key.",
          "score": 6.218,
          "start": 412
        }
      ],
      "relevance_score": 6.218
    },
    {
      "id": "b07e19d2c4a6f835",
      "source": "web",
      "rank": 2,
      "title": "Zero-downtime credential rotation",
      "url": "https://blog.example.org/zero-downtime-rotation",
      "description": "A checklist for rotating secrets in production."
    }
  ]
}

Result fields

Answer fields

Usage

Each request counts as one search. Pages read by advanced and pages fetched by scrape count as pages. Identical engine queries are cached for an hour (10 minutes for news or freshness searches) and are answered faster, but still count as a search. A request is refused with 402 when your search quota, or for advanced and scrape your page quota, is used up.

Errors

See Errors and limits for authentication errors and retries.

Related

• Research for an answer with verified citations from a full search-and-read run.
• Scrape for formats and their options.
• Usage and billing for what is metered.