> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langsearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Best Practices

> Shape queries, choose context, and build reliable search workflows.

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](/reference/search-api-guide); for the implementation contract, see [For your coding agent](/reference/search-api-guide-for-coding-agents).

## 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.

```javascript theme={null}
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                  |

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

1. Broaden an overly narrow freshness window.
2. Replace ambiguous terms with the specific concept, product, or organization.
3. Break a compound question into smaller searches.
4. 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](/api/errors) for response codes and [Plan & usage](/limits/api-limits) 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.