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

# Web Search API

> Get raw web, news, image, video, shopping, and scholar search results without LLM generation.

## Overview

Use Web Search when you need ranked search results and want to decide what to do with them yourself. It does not call an LLM.

For generated answers with citations, use the [Answer API](/answer). For full page content after search, combine Web Search with the [Scraper API](/scrape).

## Endpoint

`POST /api/v2/web_search`

## Quickstart

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { LLMLayerClient } from 'llmlayer';

  const client = new LLMLayerClient({
    apiKey: process.env.LLMLAYER_API_KEY,
  });

  const response = await client.searchWeb({
    query: 'AI regulation updates',
    searchType: 'news',
    recency: 'week',
    location: 'us',
  });

  for (const result of response.results.slice(0, 3)) {
    console.log(result.title, result.link);
  }
  ```

  ```python Python theme={null}
  from llmlayer import LLMLayerClient

  client = LLMLayerClient(api_key="YOUR_LLMLAYER_API_KEY")

  response = client.search_web(
      query="AI regulation updates",
      search_type="news",
      recency="week",
      location="us",
  )

  for result in response.results[:3]:
      print(result.get("title"), result.get("link"))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.llmlayer.dev/api/v2/web_search \
    -H "Authorization: Bearer YOUR_LLMLAYER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "AI regulation updates",
      "search_type": "news",
      "recency": "week",
      "location": "us"
    }'
  ```
</CodeGroup>

## Search Types

| Type       | Use it for           | Notes                               |
| ---------- | -------------------- | ----------------------------------- |
| `general`  | Standard web results | Default                             |
| `news`     | Recent news articles | Supports `recency`                  |
| `shopping` | Product listings     | Result fields vary by source        |
| `videos`   | Video search         | Useful before transcript extraction |
| `images`   | Image results        | Returns image-oriented metadata     |
| `scholar`  | Academic papers      | Best effort availability by query   |

## Request Parameters

| Parameter       | Type       | Required | Default   | Description                                                     |
| --------------- | ---------- | -------- | --------- | --------------------------------------------------------------- |
| `query`         | `string`   | Yes      | -         | Search query                                                    |
| `search_type`   | `string`   | No       | `general` | `general`, `news`, `shopping`, `videos`, `images`, or `scholar` |
| `location`      | `string`   | No       | `us`      | Country/location hint                                           |
| `recency`       | `string`   | No       | `null`    | `hour`, `day`, `week`, `month`, or `year`                       |
| `domain_filter` | `string[]` | No       | `null`    | Include domains, or exclude with a leading `-`                  |

<Note>
  HTTP requests use `snake_case`. The TypeScript SDK uses `camelCase`, for example `searchType` and `domainFilter`.
</Note>

## Response

```json theme={null}
{
  "results": [
    {
      "title": "Example result",
      "link": "https://www.ycombinator.com/blog",
      "snippet": "Short description..."
    }
  ],
  "cost": 0.002
}
```

| Field     | Type             | Description                                     |
| --------- | ---------------- | ----------------------------------------------- |
| `results` | `array`          | Search results. Shape depends on `search_type`. |
| `cost`    | `number \| null` | Cost in USD for the request.                    |

## Common Patterns

### Domain-constrained search

```python theme={null}
response = client.search_web(
    query="retrieval augmented generation",
    domain_filter=["arxiv.org", "openai.com", "-reddit.com"],
)
```

### Search then scrape

```typescript theme={null}
const search = await client.searchWeb({
  query: 'best practices for LLM evaluation',
  searchType: 'general',
});

const firstUrl = search.results[0]?.link;
if (typeof firstUrl === 'string') {
  const page = await client.scrape(firstUrl, {
    formats: ['markdown'],
    mainContentOnly: true,
  });
  console.log(page.markdown);
}
```

## Pricing

Web Search costs `$0.002` per request.

## Errors

| Status | Meaning                                    |
| ------ | ------------------------------------------ |
| `400`  | Missing or invalid query/search parameters |
| `401`  | Missing or invalid LLMLayer API key        |
| `429`  | Rate limit exceeded                        |
| `500`  | Search provider or internal error          |

See [Errors & Refunds](/errors) for the shared error format.

## More Examples

<CardGroup cols={2}>
  <Card title="Search + Scrape Pipeline" icon="diagram-project" href="/examples/search-scrape">
    Find pages, scrape full content, then answer with sources.
  </Card>

  <Card title="Answer API" icon="sparkles" href="/answer">
    Use search results directly with an LLM.
  </Card>
</CardGroup>