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

# Deep Search

> Deep web search with content extraction and reranking through PipeLLM WebSearch

PipeLLM exposes WebSearch through a public gateway route. Use this API when you
want web results in your own app, backend, or agent workflow without installing
the npm plugin.

## Endpoint

| Method | Endpoint                                     |
| ------ | -------------------------------------------- |
| `GET`  | `https://api.pipellm.ai/v1/websearch/search` |

## Authentication

```text theme={null}
Authorization: Bearer $PIPELLM_API_KEY
```

## Query Parameters

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `q`       | string | Yes      | Search query |

## What This Route Does

`/v1/websearch/search` is the full retrieval route. It starts with search
results, then extracts page content, runs embedding similarity, and reranks the
best contexts when available.

## Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://api.pipellm.ai/v1/websearch/search?q=latest+AI+news" \
      -H "Authorization: Bearer $PIPELLM_API_KEY"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    response = requests.get(
        "https://api.pipellm.ai/v1/websearch/search",
        params={"q": "latest AI news"},
        headers={"Authorization": f"Bearer {os.getenv('PIPELLM_API_KEY')}"},
    )

    data = response.json()
    for result in data.get("data", {}).get("organic", []):
        print(f"- {result['title']}: {result['link']}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch(
      "https://api.pipellm.ai/v1/websearch/search?q=latest+AI+news",
      {
        headers: {
          Authorization: `Bearer ${process.env.PIPELLM_API_KEY}`,
        },
      }
    );

    const data = await response.json();
    data.data.organic.forEach((result) => {
      console.log(`- ${result.title}: ${result.link}`);
    });
    ```
  </Tab>
</Tabs>

## Response Format

```json theme={null}
{
  "code": 200,
  "message": "ok",
  "took_ms": 6050,
  "data": {
    "organic": [
      {
        "title": "AI News | Latest News | Insights Powering AI-Driven Business ...",
        "link": "https://www.artificialintelligence-news.com/",
        "snippet": "AI News delivers the latest updates in artificial intelligence..."
      },
      {
        "title": "The Latest AI News and AI Breakthroughs that Matter Most",
        "link": "https://www.crescendo.ai/news/latest-ai-news-and-updates",
        "snippet": "Summary: Xiaomi has announced a next-gen AI voice model...",
        "contexts": [
          {
            "idx": 0,
            "text": "December 26, 2025\n\n# The Latest AI News and AI Breakthroughs..."
          }
        ]
      }
    ]
  }
}
```

## Response Fields

| Field                            | Type    | Description                            |
| -------------------------------- | ------- | -------------------------------------- |
| `code`                           | integer | `200` for success                      |
| `message`                        | string  | Status message                         |
| `took_ms`                        | integer | Time taken in milliseconds             |
| `data.organic`                   | array   | Organic search results                 |
| `data.organic[].title`           | string  | Page title                             |
| `data.organic[].link`            | string  | Page URL                               |
| `data.organic[].snippet`         | string  | Search snippet                         |
| `data.organic[].contexts`        | array   | Extracted page contexts when available |
| `data.organic[].contexts[].idx`  | integer | Context index                          |
| `data.organic[].contexts[].text` | string  | Extracted text content                 |

## Error Response

```json theme={null}
{
  "code": 400,
  "message": "Bad Request, missing query parameter"
}
```

## Pricing and Limits

| Item           | Value                                                                       |
| -------------- | --------------------------------------------------------------------------- |
| Price          | \$0.05 per successful request                                               |
| Limit model    | Shares your account-level limits                                            |
| Retry behavior | If you receive `503 Service Unavailable` with `Retry-After`, wait and retry |

## Example: RAG Context for an LLM

```python theme={null}
import os
import requests
from openai import OpenAI

search_response = requests.get(
    "https://api.pipellm.ai/v1/websearch/search",
    params={"q": "OpenAI o3 model capabilities"},
    headers={"Authorization": f"Bearer {os.getenv('PIPELLM_API_KEY')}"},
)
search_data = search_response.json()

context = "\n".join(
    f"[{r['title']}]({r['link']}): {r['snippet']}"
    for r in search_data.get("data", {}).get("organic", [])[:5]
)

client = OpenAI(
    api_key=os.getenv("PIPELLM_API_KEY"),
    base_url="https://api.pipellm.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": f"Use this context:\n{context}"},
        {"role": "user", "content": "What are the key features of OpenAI o3?"},
    ],
)

print(response.choices[0].message.content)
```

## Related Docs

<Columns cols={3}>
  <Card title="WebSearch Overview" icon="globe" href="/websearch/overview">
    Product overview, pricing, and entry points
  </Card>

  <Card title="Simple Search" icon="bolt" href="/websearch/simple-search">
    Faster search route without deep retrieval
  </Card>

  <Card title="pipellm-websearch (npm)" icon="box" href="/websearch/npm-package">
    Install the OpenClaw plugin from npm
  </Card>
</Columns>