---
title: "获取综合搜索 V3/Fetch general search V3"
method: POST
path: "/api/v1/douyin/search/fetch_general_search_v3"
tags: ["Douyin-Search-API"]
---

# 获取综合搜索 V3/Fetch general search V3

`POST /api/v1/douyin/search/fetch_general_search_v3`

## Request

- Base URL: `https://api.tikhub.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tikhub.io/api/v1/douyin/search/fetch_general_search_v3`
- Auth: HTTP bearer

# [中文]
### 用途:
- 获取抖音综合搜索结果（V3 版本），返回视频、用户、相关搜索词等混合卡片。
- 相比 V1/V2 不支持排序与筛选条件，但翻页参数更简单，响应结构统一（`config` + `items` + `pagination`）。

### 备注:
- 首次请求 `offset` 传 0、`page` 传 1，`search_id` 与 `backtrace` 传空字符串。
- 翻页时把上一次响应 `data.pagination` 里的 `offset`、`search_id`、`backtrace` 原样传回，并把 `page` 加 1。
- `data.pagination.has_more` 为 0 表示已经到最后一页。
- 每页固定 10 条，不支持指定数量。`page` 上限为 200，超出会返回参数错误。

### 参数:
- keyword: 搜索关键词，如 "猫咪"
- offset: 翻页游标（首次请求传 0）
- page: 页码，取值 1~200（首次请求传 1）
- search_id: 搜索ID（首次请求传空字符串）
- backtrace: 翻页回溯标识（首次请求传空字符串）

### 请求体示例：
```json
payload = {
    "keyword": "猫咪",
    "offset": 0,
    "page": 1,
    "search_id": "",
    "backtrace": ""
}
```

### 返回（部分常用字段，实际返回字段更多，一切以实际响应为准）:
- `config`: 本次搜索的配置信息（透传）
- `items[]`: 搜索结果卡片列表（已按卡片类型解包）
  - 视频卡片:
    - `aweme_id`: 视频ID
    - `desc`: 视频描述
    - `create_time`: 发布时间（时间戳）
    - `author`: 作者信息（`uid`、`sec_uid`、`nickname`、`avatar_thumb.url_list` 等）
    - `video`: 播放信息（`play_addr.url_list`、`cover.url_list`、`duration` 等）
    - `statistics`: 互动数据（`digg_count`、`comment_count`、`share_count`、`play_count`）
    - `share_url`: 视频分享链接
  - 相关搜索词卡片: 推荐词条列表
  - 其他类型卡片原样透传，不做丢弃
- `pagination`: 翻页信息
  - `offset`: 下一页的翻页游标（原样传回）
  - `cursor`: 同 `offset`
  - `search_id`: 下一页的搜索ID（原样传回）
  - `backtrace`: 下一页的回溯标识（原样传回）
  - `has_more`: 是否还有更多数据（1=有，0=无）
  - `next_page`: 下一页页码（没有更多数据时为 `null`）

# [English]
### Purpose:
- Fetch Douyin general search results (V3), returning mixed cards: videos, users, related words, etc.
- Compared with V1/V2 it has no sorting or filtering options, but pagination is simpler and the
  response structure is unified (`config` + `items` + `pagination`).

### Notes:
- For the first request set `offset` to 0, `page` to 1, and `search_id` / `backtrace` to empty strings.
- For pagination, pass back `offset`, `search_id` and `backtrace` from `data.pagination` of the
  previous response, and increment `page` by 1.
- `data.pagination.has_more` = 0 means the last page has been reached.
- Page size is fixed at 10 and cannot be changed. `page` is capped at 200;
  exceeding it returns a parameter error.

### Parameters:
- keyword: Search keyword, e.g., "cat"
- offset: Offset cursor (0 for the first request)
- page: Page number, 1-200 (1 for the first request)
- search_id: Search ID (empty for the first request)
- backtrace: Backtrace identifier (empty for the first request)

### Request Body Example:
```json
payload = {
    "keyword": "cat",
    "offset": 0,
    "page": 1,
    "search_id": "",
    "backtrace": ""
}
```

### Response (common fields, actual response may contain more fields):
- `config`: Search configuration returned by the upstream (passed through)
- `items[]`: Result cards (already unwrapped by card type)
  - Video card:
    - `aweme_id`: Video ID
    - `desc`: Video description
    - `create_time`: Publish timestamp
    - `author`: Author info (`uid`, `sec_uid`, `nickname`, `avatar_thumb.url_list`, etc.)
    - `video`: Playback info (`play_addr.url_list`, `cover.url_list`, `duration`, etc.)
    - `statistics`: Interaction data (`digg_count`, `comment_count`, `share_count`, `play_count`)
    - `share_url`: External share link
  - Related-words card: list of suggested keywords
  - Unknown card types are passed through as-is
- `pagination`: Pagination info
  - `offset`: Offset cursor for the next page (pass back as-is)
  - `cursor`: Same as `offset`
  - `search_id`: Search ID for the next page (pass back as-is)
  - `backtrace`: Backtrace for the next page (pass back as-is)
  - `has_more`: Whether more results are available (1=Yes, 0=No)
  - `next_page`: Next page number (`null` when there are no more results)

## Request body

- GeneralSearchV3Request
  - `keyword` string: 搜索关键词 / Search keyword
  - `offset` integer: 翻页游标，从上一次响应的 data.pagination.offset 获取，首次请求传 0 / Offset cursor for pagination, obtained from data.pagination.offset of the last response, 0 for the first request
  - `page` integer: 页码，取值 1~200，首次请求传 1，之后每次加 1 / Page number, 1-200, start with 1 and increment by 1 each time
  - `search_id` string: 搜索ID，从上一次响应的 data.pagination.search_id 获取，首次请求传空字符串 / Search ID, obtained from data.pagination.search_id of the last response, empty for the first request
  - `backtrace` string: 翻页回溯标识，从上一次响应的 data.pagination.backtrace 获取，首次请求传空字符串 / Backtrace, obtained from data.pagination.backtrace of the last response, empty for the first request

## Response `200`

Successful Response

- ResponseModel
  - `code` integer: HTTP status code | HTTP状态码
  - `request_id` string, nullable: Unique request identifier | 唯一请求标识符
  - `message` string: Response message (EN-US) | 响应消息 (English)
  - `message_zh` string: Response message (ZH-CN) | 响应消息 (中文)
  - `support` string: Support message | 支持消息
  - `time` string: The time the response was generated | 生成响应的时间
  - `time_stamp` integer: The timestamp the response was generated | 生成响应的时间戳
  - `time_zone` string: The timezone of the response time | 响应时间的时区
  - `docs` string, nullable: Link to the API Swagger documentation for this endpoint | 此端点的 API Swagger 文档链接
  - `cache_message` string, nullable: Cache message (EN-US) | 缓存消息 (English)
  - `cache_message_zh` string, nullable: Cache message (ZH-CN) | 缓存消息 (中文)
  - `cache_url` string, nullable: The URL to access the cached result | 访问缓存结果的 URL
  - `router` string: The endpoint that generated this response | 生成此响应的端点
  - `params` unknown
  - `data` unknown

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-08** `96a122a5f220`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-09-01** `50f9ec6e1cd3`: 1 info
  - endpoint added
- **2026-04-14** `ee5b7c9c88f5`: 1 breaking
  - api path removed without deprecation
- **2025-05-16** `14d38e4b883a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/changes/api/v1/douyin/search/fetch_general_search_v3/post.md)

---

[API](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi.md) - [All operations](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/llms.txt) - [OpenAPI document](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/revisions/86a3483c705a?raw)