# Douyin Creator audience API (douyin.creator_audience)

- Canonical page: https://everyinfra.com/en/douyin-api/creator_audience
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "douyin", "action": "creator_audience", "params": {...}}
- Price: $0.000556 per call ($0.56 per 1,000 requests); failed calls and empty results are not charged
- Returns: single object
- Mode: sync; add "mode": "async" for slow tasks

Douyin Creator audience reads who follows one creator, given the creator's `user_id`, along one `dimension`: device price band (the default), gender, age or province. Each bucket in `audience_distribution` carries the share of followers it holds, and `audience_tgi` shows how strongly that group is represented compared with the Douyin average. Brands and agencies use it to check that a creator's followers match the customers they want to reach before they book a campaign.

Shares are decimals from 0 to 1 rather than percentages, so 0.42 means 42 percent of followers; they are neither follower counts nor shares of buyers. TGI sits on a separate scale and is the number to read for fit, since a bucket with a modest share can still be strongly over-represented. For `user_id`, pass the creator's secUid, the long string that usually begins with MS4w, or the whole profile link that contains it, as the example does.

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=douyin&action=creator_audience

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| user_id | not declared | yes | not declared | The Douyin creator's `secUid`, usually beginning with `MS4w`, used to read the available audience distribution and TGI signals. Use `user_id` from creator discovery, not a nickname, short Douyin ID, or buyer identifier. |
| dimension | enum: age / device_price_band / gender / province | no | not declared | Selects the `creator_audience` follower-segment view: `device_price_band` (default), `gender`, `age`, or `province`. Distribution values are raw share decimals from 0 to 1, not percentages; TGI remains a separate index. This parameter does not request individual follower records or buyer data. |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| user_id | User's unique ID on the platform. |
| audience_distribution | platform-native meaning |
| audience_tgi | platform-native meaning |
| dimension_code | platform-native meaning |
| platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "douyin",
  "action": "creator_audience",
  "params": {
    "user_id": "https://www.douyin.com/user/MS4wLjABAAAAk1tZ-L085zZf2yW_H5dnVFZWyk8Rt8v4RAvf9KhTyPoVdMDxTs7Q_rvgTJGWXezS"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "douyin",
        "action": "creator_audience",
        "params": {
            "user_id": "https://www.douyin.com/user/MS4wLjABAAAAk1tZ-L085zZf2yW_H5dnVFZWyk8Rt8v4RAvf9KhTyPoVdMDxTs7Q_rvgTJGWXezS",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-24T18:28:34Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "douyin",
  "action": "creator_audience",
  "results": {
    "user_id": "https://www.douyin.com/user/MS4wLjABAAAAk1tZ-L085zZf2yW_H5dnVFZWyk8Rt8v4RAvf9KhTyPoVdMDxTs7Q_rvgTJGWXezS",
    "audience_distribution": [
      {
        "label": "2000~2999",
        "value": 0.21259893463305227
      },
      {
        "label": "5000~5999",
        "value": 0.16836679678233302
      },
      {
        "label": "1000~1999",
        "value": 0.14285406198106493
      }
    ],
    "audience_tgi": [
      {
        "label": "3000~3999",
        "value": 121.50162156159308
      },
      {
        "label": "7000~7999",
        "value": 107.46785052961428
      },
      {
        "label": "0~999",
        "value": 34.04478663045582
      }
    ],
    "dimension_code": "device_price_band",
    "platform": "douyin"
  },
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### What is the device price band?

`device_price_band`, the default dimension, groups a creator's followers by the price range of the phones they use, which helps when you match a product's price level with a creator's audience. As with the other dimensions, each bucket comes back as a share from 0 to 1 with its own TGI.

### What does `audience_tgi` add to the share?

TGI compares each bucket with the Douyin platform average and is measured independently of the share. A group can be a small slice of followers yet have a high TGI, meaning the creator draws that group more than Douyin does overall. Use the share to size a group and TGI to judge how distinctive the audience is.

### Can I get all four dimensions in one call?

No. Each call returns one dimension, chosen with `dimension`: `device_price_band` when you leave it out, or `gender`, `age` or `province`. Call once per dimension you need. `dimension_code` in each response records which one it holds, so results from separate calls stay labeled when you store them together.

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=douyin
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md