---
title: "Douyin Xingtu creator search"
method: GET
path: "/v1/douyin/xingtu/creators/search"
tags: ["douyin"]
---

# Douyin Xingtu creator search

`GET /v1/douyin/xingtu/creators/search`

## Request

- Base URL: `https://api.dataxapi.com`
- URL: `https://api.dataxapi.com/v1/douyin/xingtu/creators/search`
- Auth: HTTP bearer

Search Douyin creators on Xingtu by words in their name, filtered by followers, expected CPM (in yuan) and gender, or ordered by expected CPM, lowest first:Xingtu creator ID, name, location, content categories, followers; in the full view also what an integrated and a custom video cost, expected CPMs (in yuan), expected views, the last 30 days' interaction and completion ratios and median views, the e-commerce level, gender and content labels. The creator ID the other Xingtu endpoints take comes from here.

Price: $0.004 per call.

20 items on a usual page, 20 at most. A cursor is valid for 3600 seconds.

Preview: the returned object may change, announced beforehand.

## Query parameters

- `query` string, required
- `followers_min` integer
- `followers_max` integer
- `cpm_min` integer
- `cpm_max` integer
- `gender` 'female' | 'male'
- `sort` 'relevance' | 'lowest_cpm'
- `cursor` string
- `view` 'compact' | 'standard' | 'full'
- `fields` string[]

## Response `200`

OK

- object: The envelope every capability answers with.
  - `code` 'ok', required
  - `request_id` string, uuid, required
  - `data` object, required
    - `items` object[], required
      - `id` string, nullable: The creator's ID in the marketplace
      - `account_id` string, nullable: ID of the creator's account on the platform, as the platform's account endpoints take it
      - `username` string, nullable: Handle
      - `name` string, nullable: Display name
      - `avatar_url` string, uri, nullable: Avatar (standard view and up)
      - `location` string, nullable: Where the creator is based, in the platform's words (standard view and up)
      - `categories` string[], nullable: Content categories, first level, in the platform's words
      - `subcategories` string[], nullable: Content categories, second level, in the platform's words (standard view and up)
      - `metrics` object, nullable: Creator counts
        - `followers` integer, nullable: Followers
      - `approximate` object[], nullable: Which numbers of this item are approximate or lower bounds; absent when all are exact
        - `field` string, nullable: Path of the field, such as metrics.views
        - `kind` 'approximate' | 'lower_bound' | 'null', nullable: Approximate, or a lower bound
      - `ext` object: The platform's own fields (full view).
        - `uid` string, nullable: The numeric ID (uid) of the creator's Douyin account; not the ID the account endpoints take (full view)
        - `rate_integrated` string, nullable: Rate for an integrated video (植入视频: the brand placed in the creator's own content), in yuan (full view)
        - `rate_custom` string, nullable: Rate for a custom video (定制视频: a video made for the brand), in yuan (full view)
        - `expected_views` integer, nullable: Views the platform expects of one video (full view)
        - `agency` string, nullable: Name of the agency (MCN) the creator is signed to; null when there is none (full view)
        - `cpm_integrated` string, nullable: Expected cost per thousand views (CPM) of an integrated video, in yuan: the integrated rate over the views the platform expects, times 1000; null without a rate or an estimate (full view)
        - `cpm_custom` string, nullable: Expected cost per thousand views (CPM) of a custom video, in yuan, worked out the same way; null where there is none (full view)
        - `cpm_promoted` string, nullable: Xingtu's other expected cost per thousand views of an integrated video, in yuan: the same rate over the platform's promotion view estimate (not expected_views), times 1000, above or below cpm_integrated; it is what the search's CPM order (sort=lowest_cpm) goes by; null where there is none (full view)
        - `interaction_rate_30d` number, nullable: Interaction rate of the last 30 days' videos, 0 to 1 (0.0085 is 0.85%); null where the platform has none (full view)
        - `completion_rate_30d` number, nullable: Completion rate of the last 30 days' videos, 0 to 1; null where the platform has none (full view)
        - `views_median_30d` number, nullable: Median views of the last 30 days' videos (ending in .5 where the number of videos is even); null where the platform has none (full view)
        - `ecommerce_level` string, nullable: Xingtu's e-commerce (selling) level, L0 to L6, in the platform's words; null where there is none (full view)
        - `gender` 'female' | 'male' | 'null', nullable: The creator's gender: female or male; null where the platform gives none (full view)
        - `content_labels` string[], nullable: Theme labels Xingtu gives the creator's content, in the platform's words (the last 180 days', in search results); null where there are none (full view)
    - `missing` Missing[]
      - `id` string, required
      - `reason` 'not_found' | 'invalid', required
  - `page` Page: Present on capabilities that return lists. A page is asked for with `cursor`; each page is its own call and is charged on its own.
    - `next_cursor` string, nullable, required: Pass as `cursor` for the next page; null when there is none.
    - `cursor_expires_at` string, date-time, nullable, required
    - `has_more` boolean, required
    - `returned` integer, required
  - `warnings` Warning[], required
    - `code` 'items_dropped' | 'items_not_requested' | 'fields_unparsed' | 'text_truncated', required
    - `count` integer: items_dropped, items_not_requested: how many.
    - `item` integer: fields_unparsed, text_truncated: index of the item.
    - `fields` string[]
  - `meta` Meta, required
    - `capability` string, required
    - `result_status` 'complete' | 'partial' | 'empty', required
    - `fetched_at` string, date-time, required
    - `cached` boolean, required: From a shared snapshot.
    - `replayed` boolean, required: The saved result of an earlier call: `request_id` is that call's and nothing was added to the bill.
    - `unavailable` object, required: Fields this result could not carry, each with why.
    - `billing` object, required
      - `amount` string, required: US dollars, as a decimal string.
      - `currency` 'USD', required
      - `balance_after` string, nullable, required
      - `covers_next` unknown
      - `top_up_url` string, uri: With covers_next: where to top up.

## Other responses

- `4XX`: An error. Nothing was charged unless `charged` is null. - `invalid_params` (400, retry: after_fix, charged the endpoint's price where its data source billed the answer): A parameter is invalid - `request_not_served` (400, retry: after_fix): This combination of parameters cannot be served at present - `max_price_exceeded` (400, retry: after_fix): The most this call could cost is above the limit you set - `cursor_invalid` (400, retry: no): The cursor does not exist - `cursor_mismatch` (400, retry: after_fix): The cursor was issued for another endpoint or other parameters - `unauthorized` (401, retry: no): No credential was sent, or it is invalid, disabled or expired - `insufficient_balance` (402, retry: after_fix): The balance is too low - `key_budget_exceeded` (402, retry: after_fix): This key's spending limit does not cover the call - `run_budget_exceeded` (402, retry: no): This run's amount or call limit does not cover the call - `account_suspended` (403, retry: no): The account is suspended - `forbidden` (403, retry: no): This credential may not use that option - `key_scope_denied` (403, retry: no): This key may not call this endpoint - `not_found` (404, retry: no, charged the endpoint's price where its data source billed the answer): The object does not exist, is private or was deleted - `result_not_found` (404, retry: no): No result under this request ID - `run_not_found` (404, retry: no): No run under this run ID - `unknown_endpoint` (404, retry: no): There is no such endpoint - `call_in_progress` (409, retry: same_key): The call under this idempotency key is still running; ask again with the same key shortly - `idempotency_conflict` (409, retry: after_fix): This idempotency key was used for a different request - `cursor_expired` (410, retry: no): The cursor expired; start again from the first page - `result_expired` (410, retry: no): Results are kept for 24 hours; this one is gone - `run_expired` (410, retry: no): This run has expired and starts no more calls - `rate_limited` (429, retry: yes): Too many requests, or too many calls in progress - `cost_cap_exceeded` (429, retry: yes): This account's allowance for today is used up - `uncharged_cost_limit` (429, retry: yes): Too many of this account's calls today returned nothing and were not charged; endpoints of this kind can be called again tomorrow (UTC) - `settlement_unknown` (500, retry: same_key, may have been charged): Whether this call settled is not known; ask again with the same idempotency key, or look it up by request ID - `internal_error` (500, retry: yes): The service failed - `upstream_failed` (502, retry: yes): No result came back this time and nothing was charged; retry shortly - `cursor_unavailable` (502, retry: yes): This cursor is unavailable just now; retry later or start again from the first page - `upstream_busy` (503, retry: yes): Busy just now; retry shortly - `capability_paused` (503, retry: yes): This endpoint is paused - `overloaded` (503, retry: yes): The service is busy; retry shortly - `timeout` (504, retry: yes): The data did not arrive in time; retry with the same idempotency key
- `5XX`: An error. Nothing was charged unless `charged` is null. - `invalid_params` (400, retry: after_fix, charged the endpoint's price where its data source billed the answer): A parameter is invalid - `request_not_served` (400, retry: after_fix): This combination of parameters cannot be served at present - `max_price_exceeded` (400, retry: after_fix): The most this call could cost is above the limit you set - `cursor_invalid` (400, retry: no): The cursor does not exist - `cursor_mismatch` (400, retry: after_fix): The cursor was issued for another endpoint or other parameters - `unauthorized` (401, retry: no): No credential was sent, or it is invalid, disabled or expired - `insufficient_balance` (402, retry: after_fix): The balance is too low - `key_budget_exceeded` (402, retry: after_fix): This key's spending limit does not cover the call - `run_budget_exceeded` (402, retry: no): This run's amount or call limit does not cover the call - `account_suspended` (403, retry: no): The account is suspended - `forbidden` (403, retry: no): This credential may not use that option - `key_scope_denied` (403, retry: no): This key may not call this endpoint - `not_found` (404, retry: no, charged the endpoint's price where its data source billed the answer): The object does not exist, is private or was deleted - `result_not_found` (404, retry: no): No result under this request ID - `run_not_found` (404, retry: no): No run under this run ID - `unknown_endpoint` (404, retry: no): There is no such endpoint - `call_in_progress` (409, retry: same_key): The call under this idempotency key is still running; ask again with the same key shortly - `idempotency_conflict` (409, retry: after_fix): This idempotency key was used for a different request - `cursor_expired` (410, retry: no): The cursor expired; start again from the first page - `result_expired` (410, retry: no): Results are kept for 24 hours; this one is gone - `run_expired` (410, retry: no): This run has expired and starts no more calls - `rate_limited` (429, retry: yes): Too many requests, or too many calls in progress - `cost_cap_exceeded` (429, retry: yes): This account's allowance for today is used up - `uncharged_cost_limit` (429, retry: yes): Too many of this account's calls today returned nothing and were not charged; endpoints of this kind can be called again tomorrow (UTC) - `settlement_unknown` (500, retry: same_key, may have been charged): Whether this call settled is not known; ask again with the same idempotency key, or look it up by request ID - `internal_error` (500, retry: yes): The service failed - `upstream_failed` (502, retry: yes): No result came back this time and nothing was charged; retry shortly - `cursor_unavailable` (502, retry: yes): This cursor is unavailable just now; retry later or start again from the first page - `upstream_busy` (503, retry: yes): Busy just now; retry shortly - `capability_paused` (503, retry: yes): This endpoint is paused - `overloaded` (503, retry: yes): The service is busy; retry shortly - `timeout` (504, retry: yes): The data did not arrive in time; retry with the same idempotency key

---

[API](https://skmtc.dev/data-x-api/apis/openapi.md) - [All operations](https://skmtc.dev/data-x-api/apis/openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/data-x-api/apis/openapi/revisions/929c12db713d?raw)
