# Douyin KOL index scores API (Xingtu)

The Douyin KOL index scores API (Xingtu) returns the six scores Xingtu gives a Douyin creator, by Xingtu creator ID: the overall Xingtu score and those for reach, seeding, conversion, cooperation and value for money, each with the score, the average of comparable creators, the rank and how far from the top that rank is. One call costs 5 credits ($0.01 to $0.017 depending on the pack); failed calls are free. Last tested 2026-10-17.

- Page: https://socialtoai.com/douyin-kol-scores-api/
- Last updated: 2026-10-17
- Last tested: 2026-10-17

| Request | Price key | Credits |
| --- | --- | --- |
| `POST /v1/call/douyin.kol_scores` | `douyin.kol_scores` | 5 |

Preview: this interface is not marked stable yet, so its parameters and fields may still change. It is charged like any other call, and a failed call is not charged.

## Request

```bash
curl https://api.socialtoai.com/v1/call/douyin.kol_scores \
  -H "Authorization: Bearer $SOCIALTOAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "6763236383382306828"
  }'
```

```python
import os
import requests

response = requests.post(
    "https://api.socialtoai.com/v1/call/douyin.kol_scores",
    headers={"Authorization": f"Bearer {os.environ['SOCIALTOAI_KEY']}"},
    json={
        "id": "6763236383382306828",
    },
)
print(response.json())
```

## Parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | string | Required | — | Xingtu creator ID, a string of digits; not the Douyin account ID: take it from the Xingtu creator search |

## Where the values come from

- `id`: Xingtu creator ID, a string of digits; not the Douyin account ID: take it from the Xingtu creator search (e.g. `6763236383382306828`)
  Returned as `ref` by: [kol_search](https://socialtoai.com/douyin-kol-search-api.md)

## Response fields

| Field | Type | Meaning | Given |
| --- | --- | --- | --- |
| `items[].title` | string | The entry's title or name. | yes |
| `items[].url` | string | A link that opens it; null where the platform's list has none. | yes |
| `items[].rank` | integer | Position on a board, from 1. | yes |
| `items[].heat` | integer | The platform's heat score. | yes |
| `items[].fields.overall.score` | number | The overall Xingtu score, 0 to 100. | yes |
| `items[].fields.overall.average` | number | What comparable creators average on the overall Xingtu score. | yes |
| `items[].fields.overall.rank` | integer | The creator's rank on the overall Xingtu score; 1 is the highest. | yes |
| `items[].fields.overall.rank_share` | number | How near the top that rank is, 0 to 1: 0.05 means the top 5%. | yes |
| `items[].fields.reach.score` | number | The reach score, 0 to 100. | yes |
| `items[].fields.reach.average` | number | What comparable creators average on the reach score. | yes |
| `items[].fields.reach.rank` | integer | The creator's rank on the reach score; 1 is the highest. | yes |
| `items[].fields.reach.rank_share` | number | How near the top that rank is, 0 to 1: 0.05 means the top 5%. | yes |
| `items[].fields.seeding.score` | number | The seeding score, 0 to 100. | yes |
| `items[].fields.seeding.average` | number | What comparable creators average on the seeding score. | yes |
| `items[].fields.seeding.rank` | integer | The creator's rank on the seeding score; 1 is the highest. | yes |
| `items[].fields.seeding.rank_share` | number | How near the top that rank is, 0 to 1: 0.05 means the top 5%. | yes |
| `items[].fields.conversion.score` | number | The conversion score, 0 to 100. | yes |
| `items[].fields.conversion.average` | number | What comparable creators average on the conversion score. | yes |
| `items[].fields.conversion.rank` | integer | The creator's rank on the conversion score; 1 is the highest. | yes |
| `items[].fields.conversion.rank_share` | number | How near the top that rank is, 0 to 1: 0.05 means the top 5%. | yes |
| `items[].fields.cooperation.score` | number | The cooperation score, 0 to 100. | yes |
| `items[].fields.cooperation.average` | number | What comparable creators average on the cooperation score. | yes |
| `items[].fields.cooperation.rank` | integer | The creator's rank on the cooperation score; 1 is the highest. | yes |
| `items[].fields.cooperation.rank_share` | number | How near the top that rank is, 0 to 1: 0.05 means the top 5%. | yes |
| `items[].fields.value_for_money.score` | number | The value-for-money score, 0 to 100. | yes |
| `items[].fields.value_for_money.average` | number | What comparable creators average on the value-for-money score. | yes |
| `items[].fields.value_for_money.rank` | integer | The creator's rank on the value-for-money score; 1 is the highest. | yes |
| `items[].fields.value_for_money.rank_share` | number | How near the top that rank is, 0 to 1: 0.05 means the top 5%. | yes |

Every item also has platform, id, ref, approx and type; the response around the items is the same on every call. [Response format](https://socialtoai.com/docs/api/response.md)

## Sample response

Sample data: names, links and text are replaced by placeholders; the numbers are as recorded.

```json
{
  "request_id": "req_00000000-0000-4000-8000-000000000001",
  "schema_version": "v1",
  "fetched_at": "2026-10-13T03:26:38.000Z",
  "action": "call",
  "op": "douyin.kol_scores",
  "platform": "douyin",
  "status": "ok",
  "items": [
    {
      "platform": "douyin",
      "id": "…",
      "ref": "…",
      "approx": [],
      "type": "entry",
      "entry_type": "xingtu_creator_scores",
      "title": null,
      "url": null,
      "rank": null,
      "heat": null,
      "fields": {
        "overall": {
          "score": 90.9,
          "average": 56.2,
          "rank": 12,
          "rank_share": 0
        },
        "reach": {
          "score": 98.77,
          "average": 53.08,
          "rank": 232,
          "rank_share": 0.0001
        },
        "seeding": {
          "score": 98.68,
          "average": 53.26,
          "rank": 280,
          "rank_share": 0.0001
        },
        "conversion": {
          "score": 98.92,
          "average": 55.24,
          "rank": 164,
          "rank_share": 0.0001
        },
        "cooperation": {
          "score": 89.49,
          "average": 75.55,
          "rank": 1038,
          "rank_share": 0.0005
        },
        "value_for_money": {
          "score": 68.64,
          "average": 64.09,
          "rank": 50209,
          "rank_share": 0.023
        }
      }
    }
  ],
  "unavailable": [],
  "warnings": [],
  "applied_params": {
    "id": "6763236383382306828"
  },
  "cost_credits": 5,
  "billing": {
    "cost_credits": 5,
    "balance_credits": 95,
    "today_spend_credits": 5,
    "daily_limit_credits": null,
    "daily_remaining_credits": null,
    "display": "This call: 5 credits. Balance: 95 credits."
  },
  "replayed": false
}
```

## Paging and failures

- One call returns one object, with no pages, for 5 credits.
- 1 call per second per key, 5 after a purchase; going over is not charged. [Rate limits](https://socialtoai.com/docs/credits-and-billing.md#rate-limits)
- A failed call costs 0 credits and is never retried on its own. [Error codes](https://socialtoai.com/docs/api/errors.md)

## Ask your AI

- Get the six scores Xingtu gives a Douyin creator, by Xingtu creator ID: 6763236383382306828. → `call {"op":"douyin.kol_scores","id":"6763236383382306828"}`, 5 credits
- Search Douyin creators on Xingtu by words in their name: 美食, then for the first 3: get the six scores Xingtu gives a Douyin creator, by Xingtu creator ID. → `call {"op":"douyin.kol_search","query":"美食"}`, `call {"op":"douyin.kol_scores","id":"<ref>"}` × 3, 18 credits

## More on Douyin

| Interface | What it does | Price key | Credits | Page |
| --- | --- | --- | --- | --- |
| `kol_search` | Search Douyin creators on Xingtu by words in their name. | `douyin.kol_search` | 3 | https://socialtoai.com/douyin-kol-search-api.md |
| `kol_profile` | Get a Douyin creator's profile on Xingtu by Xingtu creator ID. | `douyin.kol_profile` | 3 | https://socialtoai.com/douyin-kol-profile-api.md |
| `kol_audience` | Get who follows a Douyin creator, by Xingtu creator ID. | `douyin.kol_audience` | 3 | https://socialtoai.com/douyin-kol-audience-api.md |
| `kol_performance` | Get how a Douyin creator's videos did over the last 30 or 90 days, by Xingtu creator ID. | `douyin.kol_performance` | 3 | https://socialtoai.com/douyin-kol-performance-api.md |
| `account_history` | Get how a Douyin account's numbers moved over the last 7 or 30 days, by its numeric ID, from the platform's own index tool. | `douyin.account_history` | 2 | https://socialtoai.com/douyin-account-history-api.md |
| `kol_rates` | Get what a Douyin creator charges on Xingtu for each kind of sponsored work, and how it is settled. | `douyin.kol_rates` | 24 | https://socialtoai.com/douyin-kol-rates-api.md |
| `kol_videos` | Get a page of a Douyin creator's videos by Xingtu creator ID, newest first, with the figures Xingtu gives for each. | `douyin.kol_videos` | 3 | https://socialtoai.com/douyin-kol-videos-api.md |
| `account_top_videos` | 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. | `douyin.account_top_videos` | 2 | https://socialtoai.com/douyin-account-top-videos-api.md |
| `account_audience` | Get who follows a Douyin account from the platform's own index tool, by the account's numeric ID. | `douyin.account_audience` | 2 | https://socialtoai.com/douyin-account-audience-api.md |
| `account_metrics` | Get a Douyin creator's core figures from the platform's own index tool, by the account's numeric ID. | `douyin.account_metrics` | 2 | https://socialtoai.com/douyin-account-metrics-api.md |

## FAQ

**Do I need a Douyin account or Douyin's own API access?**

No. You only need a SocialToAI key. The call returns content and account information publicly visible on Douyin; you never sign in to Douyin or apply for anything there.

**What does “Preview” mean here?**

Preview: this interface is not marked stable yet, so its parameters and fields may still change. It is charged like any other call, and a failed call is not charged.