Search Best Practices

Start with one focused query and a small result set. Refine the search when the returned evidence reveals what is missing. For a first request, see For Humans; for the implementation contract, see For your coding agent.

Write a query with a clear purpose

Include the subject and the detail you need. Avoid combining unrelated questions into a single query.

Broad query	More focused query
`caching`	`HTTP conditional requests ETag documentation`
`AI agents`	`evaluation methods for web research agents`
`database performance`	`PostgreSQL explain analyze sequential scan documentation`

For multi-part research, search each question separately, compare the sources, and let the evidence guide follow-up queries. A query is retrieval input, not a reliable way to enforce an output format or a domain restriction.

Choose the result count deliberately

Begin with 5–10 results. Increase count when you need broader source coverage, up to 50. More results also mean more context for your application to process; the maximum count is not always the most useful choice. Preserve source order initially. Select relevant evidence before adding it to a model’s context window, and avoid repeatedly including the same URL across searches.

Use the right amount of context

Need	Approach
Search UI or source list	Omit `contents` and use `snippet`
Grounded answer or research	Set `contents.text: true` and use `text`
A bounded context window	Set `contents.text: { "max_characters": 3000 }`
Citations	Keep each source’s `url` together with its title and text

Full webpage text is capped at 5000 characters per result by default. Use a positive max_characters to change the cap; the object itself enables text. Text mode replaces snippet with text. Source text can be shorter or missing, and it is evidence for your model rather than a generated answer. Select relevant sources before asking the model to synthesize them.

const sources = result.data.webPages.value.map((item) => ({
  title: item.name || item.url,
  url: item.url,
  context: item.text || item.snippet || "",
}));

Match freshness to the question

Value	Use it when
`noLimit`	Researching evergreen topics or documentation; default
`oneDay`	Looking for very recent developments
`oneWeek`	Reviewing recent announcements
`oneMonth`	Exploring developments over the past month
`oneYear`	Restricting research to the past year
`2026-09-12`	Selecting one UTC calendar day
`2026-09-01..2026-09-13`	Selecting an inclusive UTC date range

{
  "query": "recent advances in AI agent evaluation",
  "count": 10,
  "contents": {"text": true},
  "freshness": "oneMonth"
}

Date filtering depends on source metadata. It does not establish the date an event occurred or guarantee a fresh crawl. Missing publication dates are not today’s date. Dates must be valid, and the start of a range must not be after its end.

Focus on the right domains

Use structured domain filters rather than relying on the query to enforce source selection:

{
  "query": "AI search APIs",
  "count": 10,
  "freshness": "2026-09-01..2026-09-13",
  "includeDomains": ["langsearch.com", "openai.com"],
  "excludeDomains": ["reddit.com"],
  "contents": { "text": { "max_characters": 3000 } }
}

Start with a small list of relevant domains. Check spelling when a filter gives unexpected results, and avoid placing the same domain in both lists. Empty arrays apply no domain restriction. Broaden the domain or date filters before concluding that no useful evidence exists.

Refine sparse or weak results

Broaden an overly narrow freshness window.
Replace ambiguous terms with the specific concept, product, or organization.
Break a compound question into smaller searches.
Increase the result count only when you need additional coverage.

An empty array is a valid search outcome, not proof that no relevant information exists. Do not turn a network error into an empty result and silently continue.

Build reliable agent loops

Set a request timeout and a limit on search attempts. Stop when you have enough evidence to answer, or tell the user when evidence remains insufficient. For transient server failures, retry with bounded backoff and jitter. Fix invalid requests and credentials before retrying. A 429 can indicate a burst limit or exhausted daily allowance; check the error and Dashboard. Daily allowance resets automatically at 00:00 UTC. See Errors & troubleshooting for response codes and Plan & usage for account rules.

Preserve the distinction between sources and instructions

Retrieved text is untrusted external content. Keep it separate from your agent’s instructions, preserve citation URLs, and distinguish what the sources state from what the model infers. If sources disagree or lack the needed detail, make that uncertainty explicit.

API

MCP & Skills

Code examples

Account & support

Search Best Practices

Write a query with a clear purpose

Choose the result count deliberately

Use the right amount of context

Match freshness to the question

Focus on the right domains

Refine sparse or weak results

Build reliable agent loops

Preserve the distinction between sources and instructions

​Write a query with a clear purpose

​Choose the result count deliberately

​Use the right amount of context

​Match freshness to the question

​Focus on the right domains

​Refine sparse or weak results

​Build reliable agent loops

​Preserve the distinction between sources and instructions

Write a query with a clear purpose

Choose the result count deliberately

Use the right amount of context

Match freshness to the question

Focus on the right domains

Refine sparse or weak results

Build reliable agent loops

Preserve the distinction between sources and instructions