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

# Search overview

> Agentic web search with three depths and three output types: sources and snippets, sourced answers, or structured JSON.

**Search** is Linkup's synchronous web search endpoint, optimized for AI consumption. Given a natural-language query, the `/search` route returns ranked sources, optionally bundled with a cited natural-language answer or with structured output matching a JSON schema. `depth` controls how much search and retrieval work the agent performs, and `outputType` selects the shape of the response.

## Modes

**Search** comes with three `depth` modes:

| Mode         | Description                                                                                                                                   | Latency |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `"fast"`     | Sub-second latency, no query reinterpretation, no LLM. Query passed as-is to our index for retrieval.                                         | \<1s    |
| `"standard"` | Single-iteration agentic search. The agent interprets the query, can run parallel sub-searches, and can scrape one URL provided in the query. | 1–3s    |
| `"deep"`     | Multi-iteration agentic search-and-scrape chaining with evaluation.                                                                           | 5–30s   |

## Agentic search (`"standard"`, `"deep"`)

In `"standard"` and `"deep"`, the system interprets the query, plans the retrieval, and evaluates the outputs returned. This means those two modes understand instructions on how to behave/perform the search.

<Note>
  `"fast"` does not invoke an LLM. No query interpretation, no scraping — the query is passed as-is to the index.
</Note>

Depending on the prompt and the selected depth, the agent may:

* run one or several web searches,
* open and scrape webpages,
* reuse information discovered in earlier steps,
* refine or expand queries until the requested data is found.

Instructions inside the query are followed literally. The prompt below is executed step by step:

```text theme={"system"}
First, find the official website of the AI company linkup, 
then scrape the page and return the full content
```

For more information, read [search best practices](/pages/documentation/endpoints/search/best-practices).

## Output types

| Output Type       | Description                                                                                                                                                                                                                |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"searchResults"` | Array of `{name, url, content}`. Ranked URLs and content snippets for grounding.                                                                                                                                           |
| `"sourcedAnswer"` | Search results plus a natural-language answer with inline citations.                                                                                                                                                       |
| `"structured"`    | Search results plus JSON matching the caller's `structuredOutputSchema`. Requires a JSON schema in `structuredOutputSchema`; see the [structured output tutorial](/pages/documentation/tutorials/structured-output-guide). |

## Filtering and date controls

* `includeDomains` / `excludeDomains`: restrict to or exclude up to 100 domains.
* `fromDate` / `toDate`: restrict to an ISO 8601 date range.
* `maxResults`: cap the number of returned sources.
* `includeImages`: surface relevant images.

See the [domain and date filtering tutorial](/pages/documentation/tutorials/filtering)
for examples.

## Pricing

Cost depends on both `depth` and `outputType`. `"sourcedAnswer"` and `"structured"` invoke an LLM and carry a small premium over raw `"searchResults"`.

| `depth`                 | `outputType`                       | Cost             |
| ----------------------- | ---------------------------------- | ---------------- |
| `"fast"` / `"standard"` | `"searchResults"`                  | \$0.005 per call |
| `"fast"` / `"standard"` | `"sourcedAnswer"` / `"structured"` | \$0.006 per call |
| `"deep"`                | `"searchResults"`                  | \$0.05 per call  |
| `"deep"`                | `"sourcedAnswer"` / `"structured"` | \$0.055 per call |

## Example

<Card title="Get your API key" icon="key" href="https://app.linkup.so" horizontal="True">
  Create a Linkup account for free to get your API key.
</Card>

<CodeGroup>
  ```python python theme={"system"}
  from linkup import LinkupClient

  client = LinkupClient(api_key="<YOUR_LINKUP_API_KEY>")

  response = client.search(
      query="What is Microsoft's 2024 revenue?",
      depth="standard",
      output_type="sourcedAnswer",
  )
  print(response)
  ```

  ```js js theme={"system"}
  import { LinkupClient } from 'linkup-sdk';

  const client = new LinkupClient({ apiKey: '<YOUR_LINKUP_API_KEY>' });

  const response = await client.search({
    query: "What is Microsoft's 2024 revenue?",
    depth: 'standard',
    outputType: 'sourcedAnswer',
  });
  console.log(response);
  ```

  ```shell curl theme={"system"}
  curl "https://api.linkup.so/v1/search" \
    -G \
    -H "Authorization: Bearer $LINKUP_API_KEY" \
    --data-urlencode "q=What is Microsoft's 2024 revenue?" \
    --data-urlencode "depth=standard" \
    --data-urlencode "outputType=sourcedAnswer"
  ```
</CodeGroup>

Successful response, by `outputType`:

<CodeGroup>
  ```json sourcedAnswer theme={"system"}
  {
    "answer": "Microsoft's revenue for fiscal year 2024 was $245.1 billion, reflecting a 16% increase from the previous year.",
    "sources": [
      {
        "name": "Microsoft 2024 Annual Report",
        "url": "https://www.microsoft.com/investor/reports/ar24/index.html",
        "snippet": "Highlights from fiscal year 2024 compared with fiscal year 2023 included: Microsoft Cloud revenue increased 23% to $137.4 billion."
      }
    ]
  }
  ```

  ```json searchResults theme={"system"}
  {
    "results": [
      {
        "type": "text",
        "name": "Microsoft 2024 Annual Report",
        "url": "https://www.microsoft.com/investor/reports/ar24/index.html",
        "content": "Highlights from fiscal year 2024 compared with fiscal year 2023 included: Microsoft Cloud revenue increased 23% to $137.4 billion."
      }
    ]
  }
  ```
</CodeGroup>

`"structured"` returns the JSON object described by `structuredOutputSchema`.

## Next

<CardGroup cols={3}>
  <Card title="Best practices" icon="sparkles" href="/pages/documentation/endpoints/search/best-practices">
    Depth selection, query phrasing, schema design.
  </Card>

  <Card title="For AI agents" icon="robot" href="/pages/documentation/endpoints/search/for-agents">
    Tool definitions and integration prompt for coding agents.
  </Card>

  <Card title="API reference" icon="code" href="/pages/documentation/endpoints/search/reference">
    Full parameter spec and response schema.
  </Card>
</CardGroup>