Web Search

API Configuration

After saving, the Try It panel below sends real requests with this key.

Base: api.xrtoken.ai

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 or GET /v1/models for price.

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

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:

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 or `GET /v1/models`

See 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:

{ "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.

On this page