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

# Web Search

> Search the web across multiple sources including web, news, academic papers, deep research mode, and social media.

**Use this when** you want to find web pages, news articles, academic
papers, author profiles, AI-generated overviews, or social media posts
matching a search query.

The Web Search API accepts a query and returns results from one or more
source types. The result shape varies by source — always specify `sources`
explicitly when you need predictable parsing.

Every request goes to the same endpoint:

```
POST https://api.crustdata.com/web/search/live
```

<Snippet file="web-auth-headers.mdx" />

<Callout icon="lock" color="#f59e0b">
  <strong>Pricing:</strong> <code>1 credit per query</code>.
</Callout>

<Note>
  Default `rate-limit` is 10 requests per minute. Send an email to
  [gtm@crustdata.co](mailto:gtm@crustdata.co) to discuss higher limits if
  needed for your use case.
</Note>

<CardGroup cols={3}>
  <Card title="Sources" icon="shapes" href="/web-docs/search/reference#sources">
    Result shapes and field presence for each source: web, news,
    scholar-articles, scholar-author, AI, social.
  </Card>

  <Card title="Examples" icon="list-filter" href="/web-docs/search/examples">
    Site/date filtering, multi-page, academic, deep research mode, discovery
    patterns, and search → fetch workflows.
  </Card>

  <Card title="Reference" icon="book" href="/web-docs/search/reference">
    Request parameters, response body, error handling, and common gotchas.
  </Card>
</CardGroup>

***

## Your first search

The simplest search uses a `query` with an explicit `sources` array. Always
specify `sources` for predictable result parsing.

<CodeGroup>
  ```bash Request theme={"theme":"vitesse-black"}
  curl --request POST \
    --url https://api.crustdata.com/web/search/live \
    --header 'authorization: Bearer YOUR_API_KEY' \
    --header 'content-type: application/json' \
    --header 'x-api-version: 2025-11-01' \
    --data '{
      "query": "crustdata",
      "sources": ["web"],
      "location": "US"
    }'
  ```

  ```json Response theme={"theme":"vitesse-black"}
  {
      "success": true,
      "query": "crustdata",
      "timestamp": 1775195367446,
      "results": [
          {
              "source": "web",
              "title": "Crustdata: Real-Time B2B Data Broker via API or Data Feed",
              "url": "https://crustdata.com/",
              "snippet": "Crustdata is a B2B data provider offering real-time company & people datasets. Access APIs and live signals to power sales and investment workflows.",
              "position": 1
          },
          {
              "source": "web",
              "title": "Crustdata: Real-time B2B data via simple APIs",
              "url": "https://www.ycombinator.com/companies/crustdata",
              "snippet": "Crustdata provides live company and people data via APIs and full dataset delivery.",
              "position": 2
          }
      ],
      "metadata": {
          "total_results": 7,
          "failed_pages": [],
          "empty_pages": []
      }
  }
  ```
</CodeGroup>

<Note>Response trimmed for clarity.</Note>

**Extract:** Each result in `results[]` contains `source`, `title`, `url`,
`snippet`, and `position`. Use `position` for ranking and `url` for
follow-up fetching.

***

## Use human mode when standard retrieval is blocked

Set `human_mode: true` when you want the API to attempt a browser-like
retrieval path for the search request.

<CodeGroup>
  ```bash Request theme={"theme":"vitesse-black"}
  curl --request POST \
      --url https://api.crustdata.com/web/search/live \
      --header 'authorization: Bearer YOUR_API_KEY' \
      --header 'content-type: application/json' \
      --header 'x-api-version: 2025-11-01' \
      --data '{
          "query": "crustdata",
          "sources": ["web"],
          "human_mode": true
      }'
  ```
</CodeGroup>

<Note>
  **Current platform behavior:** `human_mode: true` returns the normal search
  response shape with `success`, `query`, `timestamp`, `results`, and
  `metadata`.
</Note>

***

## What to do next

* **Understand result shapes** — see [Sources](/web-docs/search/reference#sources) for field presence by source.
* **Try more patterns** — see [Examples](/web-docs/search/examples) for site/date filtering, discovery, and workflows.
* **Look up request/response details** — see [Reference](/web-docs/search/reference).
* **Fetch page content** — see [Web Fetch](/web-docs/fetch/introduction) to fetch HTML content of URLs returned by search.