---
title: "Douyin trend-index keyword trends"
method: GET
path: "/v1/douyin/index/keywords/history"
tags: ["douyin"]
---

# Douyin trend-index keyword trends

`GET /v1/douyin/index/keywords/history`

## Request

- Base URL: `https://api.dataxapi.com`
- URL: `https://api.dataxapi.com/v1/douyin/index/keywords/history`
- Auth: HTTP bearer

Get the day-by-day search index and composite index of a keyword, or of one to five keywords at once, on Douyin over a date range, from 巨量算数 (the Douyin index), with the daily averages of the period, of the one before and of a year earlier. An index is the platform's score of volume, not a count of searches; days are calendar days in China time (UTC+8).

Price: $0.006 per call.

Give exactly one of keywords, keyword.

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

A keyword the index does not cover is not in the answer; when none of the keywords asked for has figures the result is empty, never a not-found error. Asking only for days the platform has not published yet is an empty result too.

Preview: the returned object may change, announced beforehand.

## Query parameters

- `keyword` string
- `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
      - `keyword` string, nullable: The keyword
      - `points` object[], nullable: The figures day by day, one entry a day, oldest first
        - `date` string, date-time, nullable: The day: a calendar day in China time (UTC+8), written as midnight UTC of its date (8 a.m. that day in China); passed back as since or until it asks for that same day
        - `search_index` integer, nullable: Search index of the day: the platform's index of how much the keyword was searched, not a count of searches
        - `composite_index` integer, nullable: Composite index of the day: the platform's index of how much attention content about the keyword drew, not a count
        - `notes` integer, nullable: Posts about the keyword that day (standard view and up)
        - `impressions` integer, nullable: Times those posts were shown that day (standard view and up)
        - `views` integer, nullable: Times those posts were read that day (standard view and up)
        - `engagements` integer, nullable: Engagements with those posts that day (standard view and up)
      - `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).
        - `composite_average` integer, nullable: Daily average of the composite index over the period asked for (full view)
        - `search_average` integer, nullable: Daily average of the search index over the period asked for (full view)
        - `previous_composite_average` integer, nullable: Daily average of the composite index over the period of the same length before it (full view)
        - `previous_search_average` integer, nullable: Daily average of the search index over the period of the same length before it (full view)
        - `year_ago_composite_average` integer, nullable: Daily average of the composite index over the same period a year earlier (full view)
        - `year_ago_search_average` integer, nullable: Daily average of the search index over the same period a year earlier (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)
