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

> ## Agent Instructions
> Setting up Context.dev for a user? Follow https://docs.context.dev/agent-quickstart.md. MCP clients sign in with OAuth and need no API key; application code reads CONTEXT_DEV_API_KEY.

# Search

> Find web pages from a query and optionally read each result’s content.

Search returns ranked URLs with titles, descriptions, and relevance information. Enable page content when you want Markdown alongside the results.

## Search the web

Start with a query and the number of results. See the [Quickstart](/quickstart) for authentication and SDK setup.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import ContextDev from "context.dev";

  const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });
  const search = await client.web.search({ query: "Stripe API authentication", numResults: 10 });

  console.log(search.results);
  ```

  ```python Python theme={null}
  import os
  from context.dev import ContextDev

  client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])
  search = client.web.search(query="Stripe API authentication", num_results=10)

  print(search.results)
  ```

  ```ruby Ruby theme={null}
  require "cgi/core"
  require "context_dev"

  client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))
  search = client.web.search(query: "Stripe API authentication", num_results: 10)

  pp search.results
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "os"

      contextdev "github.com/context-dot-dev/context-go-sdk/v2"
      "github.com/context-dot-dev/context-go-sdk/v2/option"
  )

  func main() {
      client := contextdev.NewClient(option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")))
      search, err := client.Web.Search(context.Background(), contextdev.WebSearchParams{
          Query:      "Stripe API authentication",
          NumResults: contextdev.Int(10),
      })
      if err != nil {
          panic(err)
      }

      fmt.Printf("%+v\n", search.Results)
  }
  ```

  ```php PHP theme={null}
  <?php

  require __DIR__.'/vendor/autoload.php';

  use ContextDev\Client;

  $client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));
  $search = $client->web->search(query: 'Stripe API authentication', numResults: 10);

  print_r($search->results);
  ```

  ```bash cURL theme={null}
  curl https://api.context.dev/v1/web/search \
    -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "Stripe API authentication", "numResults": 10}'
  ```
</CodeGroup>

Read `results` for ranked pages. Request fields and the complete response are in the [Search reference](/api-reference/web-scraping/search).

## Choose what to return

`numResults` ranges from 10 to 100 and defaults to 10. The actual number returned can be smaller. Use [filters](/search/filters) to restrict domains, recency, and location. [Result content](/search/page-content) covers page reads and per-result failures.

Set `timeoutOpts.behavior` to `return-partial` if a subset of results is useful at your deadline, and inspect `partial`.

Use [Scrape](/scrape/overview) when you already know the URL. Use [Answers](/answers/overview) when you want a researched answer in a specific JSON shape.