Search or Extract: picking the right endpoint

WebSearch V1 ships exactly two write endpoints: /api/search and /api/extract. The boundary is simple — Search discovers, Extract reads. But when to use which, and how to parameterize them, deserves a closer look.

The decision path

Do you already have the URL?
├─ Yes → Extract directly, skip Search
└─ No → Search first
         ├─ Snippets answer the question → stop here
         └─ Need full text → Extract the top hits

The most common waste: the snippets from Search already answered the question, yet every URL gets Extracted anyway. Check whether the content field is enough before going deeper.

Search: two cost dials

search_depth is the big one:

• basic (1 credit) — titles, URLs, snippets. Enough for most Q&A.
• advanced (2 credits) — additionally fetches each result's page text. Use it when you need to quote sources verbatim.

max_results defaults to 5, capped at 20. More results mean slower advanced searches, since each page gets fetched. Start at 5, widen if needed.

Domain filters go in include_domains / exclude_domains and are pushed down to the provider when supported — cheaper than filtering client-side:

{
  "query": "retrieval augmented generation",
  "search_depth": "basic",
  "max_results": 5,
  "include_domains": ["arxiv.org"]
}

Extract: billed per success, failures are free

Extract accepts up to 20 URLs per call and bills 1 credit per 5 successful URLs (2 on advanced). Pages that fail land in failed_results and cost nothing — so batch freely.

{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "extract_depth": "basic",
  "format": "markdown"
}

• format: "markdown" (default) keeps headings and lists — ideal for model context. "text" is plain text, better for embeddings.
• advanced preserves tables and waits longer for JS-heavy pages. Start with basic; upgrade when failure rates climb.

A complete agent loop

# 1. Discover
curl -X POST $BASE/api/search \
  -H "Authorization: Bearer $KEY" \
  -d '{"query": "latest AI progress", "max_results": 3}'

# 2. Read the top hit
curl -X POST $BASE/api/extract \
  -H "Authorization: Bearer $KEY" \
  -d '{"urls": ["https://example.com/ai-news"]}'

# 3. Check the meter
curl $BASE/api/usage -H "Authorization: Bearer $KEY"

Total cost of this task: 2 credits — one basic search plus one single-URL extract. The Usage page shows the per-endpoint breakdown.