# Web Search

Get web results for a query in one request. Typical uses: agent tools, RAG retrieval, research aggregation.

- **Endpoint**: `POST /v1/search`
- **Auth**: `Authorization: Bearer tr-...` (same as other `/v1` APIs)
- **Billing**: **Per successful call**; failures are not charged. See [Model Marketplace](/dashboard/models) or `GET /v1/models` for price.

Field details: [Web Search API](/docs/api/createSearch).

## Search types (`Type`)

| `Type` | Model ID | Notes |
| --- | --- | --- |
| `web` | `doubao-web-search` | Web search; only `SearchType=web` in this release |
| `global` | `doubao-global-search` | Global search; request fields differ from `web` |

Select the product line with body `Type`. Models appear in `GET /v1/models` (`model_type: search`).

## Quick start

```bash
export XRT_API_KEY="tr-xxxxxxxx"
export XRT_BASE="https://api.xrtoken.net"   # CN

# Web search
curl -sS "$XRT_BASE/v1/search" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Type": "web",
    "Query": "Beijing day trip ideas",
    "Count": 5,
    "SearchType": "web"
  }'

# Global search
curl -sS "$XRT_BASE/v1/search" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Type": "global",
    "Query": "openai research",
    "DocCount": 5,
    "MaxSnippetLength": 500
  }'
```

Python:

```python
import os
import requests

BASE = os.environ.get("XRT_BASE", "https://api.xrtoken.net")
KEY = os.environ["XRT_API_KEY"]

resp = requests.post(
    f"{BASE}/v1/search",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Content-Type": "application/json",
    },
    json={
        "Type": "web",
        "Query": "tech news today",
        "Count": 10,
        "SearchType": "web",
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
for item in (data.get("Result") or {}).get("WebResults") or []:
    print(item.get("Title"), item.get("Url"))
```

## Request fields

### Gateway fields

| Field | Required | Description |
| --- | --- | --- |
| `Type` | Yes | `web` or `global` |
| `model` | No | If set, must match Type |

### Type = web

| Field | Required | Description |
| --- | --- | --- |
| `Query` | Yes | Query string, 1–100 characters |
| `SearchType` | No | Defaults to `web`; `image` is not supported yet |
| `Count` | No | Result count, max 50, default 10 |
| `Filter` | No | `NeedContent` / `NeedUrl` / `Sites` / `BlockHosts` / `AuthInfoLevel` |
| `TimeRange` | No | `OneDay` / `OneWeek` / `OneMonth` / `OneYear` or date range |
| `QueryControl.QueryRewrite` | No | Query rewrite (adds latency) |
| `ContentFormats` | No | `text` / `markdown` |
| `Industry` | No | `finance` / `game` / `gov` |

### Type = global

| Field | Required | Description |
| --- | --- | --- |
| `Query` | Yes | Query string, 1–100 characters |
| `DocCount` | No | Result count, max 20, default 10 |
| `MaxSnippetLength` | No | Max tokens per snippet (recommend ≤1000, max 3000) |
| `MaxImageCountPerDoc` | No | Max images per doc, default 3, max 10 |

## Response

- HTTP is usually **200**; body is JSON with `ResponseMetadata` and `Result`.
- Response header **`X-Request-Id`** (`tr-req-...`) for support.
- **web**: `Result.WebResults[]` (`Title` / `Url` / `Snippet` / `Summary` / `Content`).
- **global**: `Result.Documents[]` and `TotalDocCount`.

For LLM contexts prefer **`Summary`** when present; `Snippet` is for list UI only.

## Billing

| Item | Rule |
| --- | --- |
| Method | Per successful call |
| Result count | Does **not** change the unit price |
| Failures | Validation errors, insufficient balance, service errors: **no charge** |
| Price | See [Model Marketplace](/dashboard/models) or `GET /v1/models` |

See [Billing](/docs/billing) for freeze/settle details.

## Errors

| HTTP | Typical cause |
| --- | --- |
| 400 | Missing `Type`/`Query`, `SearchType=image`, `DocCount>20`, model/Type mismatch |
| 401 | Invalid API key |
| 402 | Insufficient balance |
| 429 | Rate limited |
| 502 / 503 | Temporary service issue |

Local validation example:

```json
{ "error": "Query is required", "type": "invalid_request_error" }
```

## Limits

- **CN edition** in this release (`api.xrtoken.net`); check `GET /v1/models` for availability.
- Image search (`SearchType=image`) is not enabled.
- Synchronous API — no async task polling.
- Control concurrency reasonably.

## Related

- [API: POST /v1/search](/docs/api/createSearch)
- [Authentication](/docs/authentication)
- [Models](/docs/models)
- [Billing](/docs/billing)
- [Errors](/docs/errors)