---
title: "Douyin trend-index creator top videos"
method: GET
path: "/v1/douyin/index/creators/videos/list"
tags: ["douyin"]
---

# Douyin trend-index creator top videos

`GET /v1/douyin/index/creators/videos/list`

## Request

- Base URL: `https://api.dataxapi.com`
- URL: `https://api.dataxapi.com/v1/douyin/index/creators/videos/list`
- Auth: HTTP bearer

Get the videos the platform's own index tool lists as a Douyin account's top videos for a span of up to 30 days, by the account's numeric ID: up to twenty, most liked first, each with caption, link, day published, its engagement counts and followers gained. As recorded, the tool picks from what was published on the last day or two of the span, not from all of it: set the end date to the day you want. One page; no view counts.

Price: $0.002 per call.

20 items on a usual page, 20 at most. Given whole: there is no next page.

An account that does not exist cannot be told from an account with no videos in the span: both return an empty result, not a 404.

## Query parameters

- `id` string, required
- `since` string, date-time, required
- `until` string, date-time, required
- `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: ID; pass it unchanged to the get endpoint
      - `url` string, uri, nullable: Link that opens the post
      - `type` 'video' | 'image' | 'text' | 'article' | 'null', nullable: Content format
      - `title` string, nullable: Title
      - `text` string, nullable: Body text
      - `lang` string, nullable: Language of the text (standard view and up)
      - `published_at` string, date-time, nullable: When it was published
      - `author` object, nullable: Author
        - `id` string, nullable: Author's account ID
        - `username` string, nullable: Author's handle
        - `name` string, nullable: Author's display name
        - `avatar_url` string, uri, nullable: Author's avatar (standard view and up)
        - `verified` boolean, nullable: Whether the author is verified (standard view and up)
        - `followers` integer, nullable: Author's follower count (standard view and up)
      - `metrics` object, nullable: Engagement counts
        - `likes` integer, nullable: Likes
        - `comments` integer, nullable: Comments
        - `shares` integer, nullable: Shares
        - `favorites` integer, nullable: Saves
        - `views` integer, nullable: Views
        - `reposts` integer, nullable: Reposts
      - `images` string[], nullable: Image addresses (standard view and up)
      - `hashtags` string[], nullable: Hashtags, without the # (standard view and up)
      - `mentions` object[], nullable: Accounts mentioned in the text (standard view and up)
        - `id` string, nullable: Account ID (standard view and up)
        - `username` string, nullable: Handle (standard view and up)
        - `name` string, nullable: Display name (standard view and up)
      - `is_pinned` boolean, nullable: Whether the author pinned it (standard view and up)
      - `post_id` string, nullable: ID of the thread's root post when this is a reply; otherwise null
      - `parent_id` string, nullable: ID of the item it replies to directly; otherwise null
      - `root_id` string, nullable: ID of the first-level reply its thread hangs under
      - `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).
        - `new_followers` integer, nullable: Followers the post gained its author (full view)
        - `like_rate` number, nullable: Like rate: likes over views, 0 to 1 (full view)
        - `follow_rate` number, nullable: Follow rate: new followers over views, 0 to 1 (full view)
        - `index` integer, nullable: The index 巨量算数 gives the video: a score, not a count of plays (full view)
        - `category` string, nullable: The category the video is filed under, in the platform's words (full view)
        - `cover_url` string, uri, nullable: Address of the cover image (full view)
        - `duration` number, nullable: Length of the video, in seconds; an image post has none (full view)
        - `video_url` string, uri, nullable: Address the video plays from: a signed address of the platform's that expires, so use it soon; an image post has none (full view)
        - `finish_rate` number, nullable: Completion rate: the share of plays watched to the end, 0 to 1 (Xingtu's figure) (full view)
        - `interaction_rate` number, nullable: Interaction rate: interactions over plays, 0 to 1 (Xingtu's figure) (full view)
        - `categories` string[], nullable: What the platform files the post under, from the first level to the third, in its words (such as 美食 › 美食教程 › 饮品教程, food › food tutorials › drink tutorials); null where it filed it under none (full view)
        - `author_xingtu_id` string, nullable: The author's Xingtu creator ID, as the other Xingtu endpoints take it (Xingtu's figure) (full view)
        - `author_uid` string, nullable: The numeric ID (uid) of the author's Douyin account, what the trend-index creator endpoints take (Xingtu's figure) (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)
