--- title: "获取用户搜索/Fetch user search" method: POST path: "/api/v1/douyin/search/fetch_user_search" tags: ["Douyin-Search-API"] --- # 获取用户搜索/Fetch user search `POST /api/v1/douyin/search/fetch_user_search` ## 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_user_search` - Auth: HTTP bearer # [中文] ### 用途: - 获取抖音 App 中根据关键词搜索到的用户列表。 - 支持通过粉丝数量、用户类型进行筛选查询。 ### 备注: - 初次请求 `cursor` 传 0，`search_id` 传空字符串。 - 返回的数据仅包含「用户信息」，不包括视频、话题、音乐等内容。 ### 参数: - keyword: 搜索关键词，如 "人工智能" - cursor: 翻页游标（首次请求传0） - douyin_user_fans: 粉丝数量筛选 - 为空: 不限 - "0_1k": 1000以下 - "1k_1w": 1000到1万 - "1w_10w": 1万到10万 - "10w_100w": 10万到100万 - "100w_": 100万以上 - douyin_user_type: 用户类型筛选 - 为空: 不限 - "common_user": 普通用户 - "enterprise_user": 企业认证用户 - "personal_user": 个人认证用户 - search_id: 搜索ID（翻页使用） ### 请求体示例： ```json payload = { "keyword": "人工智能", "cursor": 0, "douyin_user_fans": "", "douyin_user_type": "", "search_id": "" } ``` ### 返回（部分常用字段，实际返回字段更多，一切以实际响应为准）: - `cursor`: 下一页游标 - `has_more`: 是否还有更多数据（1=有，0=无） - `user_list[]`: 用户列表 - `user_info`: - `uid`: 用户ID - `nickname`: 用户昵称 - `gender`: 性别（0=未知，1=男，2=女） - `unique_id`: 抖音号 - `sec_uid`: 安全UID - `signature`: 个性签名 - `follower_count`: 粉丝数量 - `avatar_thumb.url_list`: 小头像地址 - `avatar_medium.url_list`: 中头像地址 - `avatar_larger.url_list`: 大头像地址 - `follow_status`: 是否已关注 - `live_status`: 是否正在直播（0=否，1=是） - `enterprise_verify_reason`: 企业认证信息（若有） - `versatile_display`: 抖音号展示文案（例如"抖音号：xxx"） - `extra`: - `now`: 当前服务器时间戳 - `logid`: 请求日志ID - `search_request_id`: 搜索请求ID # [English] ### Purpose: - Fetch a list of users from Douyin App based on search keywords. - Supports filtering by fan count and user type. ### Notes: - Set `cursor` to 0 and `search_id` to an empty string for the first request. - Only user information is returned. No videos, music, or hashtags. ### Parameters: - keyword: Search keyword, e.g., "AI" - cursor: Pagination cursor (0 for first page) - douyin_user_fans: Fan count filter - Empty: No limit - "0_1k": Below 1000 fans - "1k_1w": 1,000 to 10,000 fans - "1w_10w": 10,000 to 100,000 fans - "10w_100w": 100,000 to 1,000,000 fans - "100w_": Above 1,000,000 fans - douyin_user_type: User type filter - Empty: No limit - "common_user": Regular user - "enterprise_user": Enterprise-verified user - "personal_user": Personal-verified user - search_id: Search session ID for pagination ### Request Body Example: ```json payload = { "keyword": "AI", "cursor": 0, "douyin_user_fans": "", "douyin_user_type": "", "search_id": "" } ``` ### Response (common fields, actual response may contain more fields): - `cursor`: Cursor for next page - `has_more`: Whether more data is available (1=Yes, 0=No) - `user_list[]`: List of users - `user_info`: - `uid`: User ID - `nickname`: Nickname - `gender`: Gender (0=Unknown, 1=Male, 2=Female) - `unique_id`: Douyin ID - `sec_uid`: Secured UID - `signature`: Personal bio - `follower_count`: Number of followers - `avatar_thumb.url_list`: List of thumbnail avatar URLs - `avatar_medium.url_list`: List of medium avatar URLs - `avatar_larger.url_list`: List of large avatar URLs - `follow_status`: Whether followed - `live_status`: Whether live - `enterprise_verify_reason`: Enterprise verification info (if any) - `versatile_display`: Display text (e.g., "Douyin ID: xxx") - `extra`: - `now`: Current server timestamp - `logid`: Request log ID - `search_request_id`: Search request ID ## Request body - AppApiV1EndpointsDouyinSearchUserSearchRequest - `keyword` string: 关键词 / Keyword - `cursor` integer: 偏移游标，用于翻页，从上一次请求返回的响应中获取 / Offset cursor for pagination, obtained from the last response - `douyin_user_fans` string: 粉丝数过滤：空=不限 0_1k=1千以下 1k_5k=1千到5千 5k_10k=5千到1万 10k_100k=1万到10万 100k_1M=10万到100万 1M_=100万以上 / Fans filter: empty=No limit, 0_1k=Under 1k, etc. - `douyin_user_type` string: 用户类型过滤：空=不限 300=创作者 900=小店 700=音乐人 800=明星 / User type filter: empty=No limit, 300=Creator, 900=Shop, 700=Musician, 800=Celebrity - `search_id` string: 搜索ID，用于翻页，从上一次请求返回的响应中获取 / Search ID for pagination, obtained from the last response ## 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`: 2 info - the `cache_message` response's property default value changed from `This request will be cached. You can access the cached result directly using the URL below, valid for 24 hours. Accessing the cache will not incur additional charges.` to `This response is cached and accessible via the URL below for 24 hours at no extra cost. The cache is for request tracing only — it doesn't affect the API's data freshness and won't be returned through the API again.` for the status `200` - the `cache_message_zh` response's property default value changed from `本次请求将被缓存，你可以使用下面的 URL 直接访问缓存结果，有效期为 24 小时，访问缓存不会产生额外费用。` to `本次响应已缓存，可通过下方 URL 直接查看，有效期 24 小时，访问缓存链接无额外费用。缓存仅用于请求溯源，不影响接口数据的时效性，也不会再次通过接口返回。` for the status `200` - **2026-04-14** `ee5b7c9c88f5`: 11 info - added the optional property `cache_message` to the response with the `200` status - added the optional property `cache_message_zh` to the response with the `200` status - added the optional property `cache_url` to the response with the `200` status - added the optional property `docs` to the response with the `200` status - …7 more - **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_user_search/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)