# Search

Search the web for a query and return a ranked list of structured results. See the [Search & Fetch guide](https://api-docs.deepseek.com/guides/search.md) for supported query operators, error handling, and billing.

## Endpoint

```http
POST /v1/tools/search
```

operationId: `search`

### Servers

- `https://api.deepseek.com`

## Authentication

### Alternative 1

**bearerAuth**

`Authorization: Bearer <API_KEY>`

```yaml
type: http
scheme: bearer
```

## Request body

**required**

### application/json

- Reference: [SearchRequest](#schema-search-request) (`#/components/schemas/SearchRequest`)

## Responses

### 200

OK, returns the search results.

#### application/json

- Reference: [SearchResponse](#schema-search-response) (`#/components/schemas/SearchResponse`)

**Example**

```json
{
  "results": [
    {
      "rerank_score": 2.4,
      "title": "DeepSeek V4 model released",
      "url": "https://example.com/deepseek-v4",
      "snippet": "DeepSeek V4 is now available, with tool calling and long-context support.",
      "summary": "DeepSeek has released the V4 model. The release adds improved tool calling and long-context support for agent workflows.",
      "content": "",
      "site_name": "Example News",
      "site_icon": "https://example.com/favicon.ico",
      "date": "2026-06-01T00:00:00+00:00",
      "authority": 3
    }
  ]
}
```

## Code samples

### curl

```bash
# Set DEEPSEEK_API_KEY to your API key before running this example.
curl --silent --show-error --max-time 60 "https://api.deepseek.com/v1/tools/search" \
  --header "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "query": "DeepSeek API documentation",
  "count": 1,
  "need_content": false
}'
```

### Python — requests

```python
# Set DEEPSEEK_API_KEY to your API key before running this example.
import os
import requests

response = requests.post(
    "https://api.deepseek.com/v1/tools/search",
    headers={"Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}"},
    json={
        "query": "DeepSeek API documentation",
        "count": 1,
        "need_content": False,
    },
    timeout=60,
)
response.raise_for_status()
for result in response.json()["results"]:
    print(result["title"], result["url"])
    print(result["summary"])
```

## Referenced schemas

### schema-search-request

**SearchRequest** — `#/components/schemas/SearchRequest`

- `type`: `object`

- `required`: `["query"]`

- **Properties**

  - **`query`** (required)

    The search query. Supports operators such as `site:`, `-site:`, and quoted phrases. Must contain 1 to 128 Unicode characters and cannot be all whitespace.

    - `type`: `string`

    - `minLength`: `1`

    - `maxLength`: `128`

  - **`count`** (optional)

    The number of results to return, between 1 and 50. Defaults to 10.

    - `type`: `integer`

    - `minimum`: `1`

    - `maximum`: `50`

    - `default`: `10`

  - **`ori_question`** (optional)

    The user's original question that triggered the search, between 1 and 128 characters. Providing it can improve query understanding. `null` is treated as not provided.

    - `type`: `string`

    - `nullable`: `true`

    - `minLength`: `1`

    - `maxLength`: `128`

  - **`localization`** (optional)

    An optional IP address used to localize search results. Defaults to an empty string.

    - `type`: `string`

    - `default`: `""`

  - **`need_content`** (optional)

    Whether to return page content in `content`. Defaults to `false`; when `false`, `content` is always an empty string.

    - `type`: `boolean`

    - `default`: `false`

### schema-search-response

**SearchResponse** — `#/components/schemas/SearchResponse`

- `type`: `object`

- `required`: `["results"]`

- **Properties**

  - **`results`** (required)

    The search results. Empty when the query matches no results.

    - `type`: `array`

    - **Array items**

      - Reference: [SearchResult](#schema-search-result) (`#/components/schemas/SearchResult`)

### schema-search-result

**SearchResult** — `#/components/schemas/SearchResult`

- `type`: `object`

- `required`: `["rerank_score","title","url","snippet","summary","content","site_name","site_icon","date","authority"]`

- **Properties**

  - **`rerank_score`** (required)

    A relevance score from 0 to 3 that combines signals such as relevance, authority, and freshness. Scores of 1.5 or above are considered high-quality results.

    - `type`: `number`

    - `format`: `float`

    - `minimum`: `0`

    - `maximum`: `3`

  - **`title`** (required)

    The title of the search result.

    - `type`: `string`

  - **`url`** (required)

    The URL of the search result.

    - `type`: `string`

  - **`snippet`** (required)

    A short summary related to the query, typically 100 to 200 characters, intended for display in a UI.

    - `type`: `string`

  - **`summary`** (required)

    A long summary related to the query, typically 600 to 800 characters, intended to be read by a model.

    - `type`: `string`

  - **`content`** (required)

    The page content. Empty when `need_content` is `false` or when the content is unavailable.

    - `type`: `string`

  - **`site_name`** (required)

    The name of the site, or `null` when unavailable.

    - `type`: `string`

    - `nullable`: `true`

  - **`site_icon`** (required)

    The URL of the site icon, or `null` when unavailable.

    - `type`: `string`

    - `nullable`: `true`

  - **`date`** (required)

    The publication time in UTC, formatted as RFC 3339, or `null` when unknown.

    - `type`: `string`

    - `format`: `date-time`

    - `nullable`: `true`

    **Example**

    ```json
    "2026-06-01T00:00:00+00:00"
    ```

  - **`authority`** (required)

    The authority tier of the page, 0 to 4 (`-1` means unknown). Values of 3 or above indicate highly authoritative sources.

    - `type`: `integer`

    - `minimum`: `-1`

    - `maximum`: `4`