Douyin Fetch Creator Live Room History List

2.07 credits/call
ae_douyin_fetch_creator_live_room_history_list

## Purpose Retrieve live-session history for the Douyin creator account associated with a valid Douyin Creator Platform cookie. Use the records to review sessions and compare audience, engagement and consumption metrics across a date range. Ongoing sessions can optionally be included. ## Inputs Provide a required `request_body` object containing: - `cookie` (required string): a valid Creator Platform cookie for the account you are authorized to access. Treat it as sensitive account information. - `start_date` and `end_date` (required strings): date boundaries in `YYYY-MM-DD` format. - `limit` (optional integer): record limit, default 400; documented maximum 400. - `need_living` (optional integer): `0` excludes ongoing sessions; `1` includes them. Default: `1`. - `download` (optional integer): `0` disables downloading; `1` enables it. Default: `0`. A separate download response format is not documented. ## Results The documented session list is at `data.data.series`. Each session may contain: - Basic details: `roomID` (room ID), `roomTitle` (title), `coverUri` (cover image URL), `startTime` and `endTime` (timestamps formatted as `YYYY-MM-DD HH:mm:ss`), `liveDurationWithoutPause` (duration excluding pauses), and `playStatus` (`4` means ended). - Audience metrics: `watchCnt` (total views), `serverWatchUcntTdDirect` (direct viewing users), `pcu` (peak concurrent viewers), and `liveServerWatchDurationTdPavg` (average watch duration). - Engagement: `serverLikeCntTd` (likes), `clientCommentUcntTd` (commenting users), and `liveNewFollowUcnt` (new followers). - Consumption: `liveConsumeUcnt` (consuming users), `liveFansConsumeUcntTd` (fan consuming users), and `roomLiveEarnScore` (earnings score, not a currency amount). Metric values are shown as strings in the documented example. The unit of average watch duration is not specified. ## Limits and freshness At most 400 records are returned per request, so a response need not cover every session in a large date range. The documentation recommends ranges of no more than three months and notes possible data delays of 1–2 hours. An expired cookie can prevent retrieval; including ongoing sessions does not guarantee real-time metrics.

SocialVideo
2.07 credits/call

Pricing

2.07 credits/call
ConditionCharge
Each call2.07 credits/call

Each call has a fixed charge of 2.07 credits. Charges are per query. A successful query is billed even if it returns no results.

Parameters

Optional parameters use the platform defaults when omitted.

ParameterTypeRequiredDescriptionDefault
request_bodyobjectYes直播场次历史记录请求参数/Live room history list request parameters—
request_body.limitintegerNo每页数量限制/Limit per page (最多400条)400
request_body.cookiestringYes用户Cookie/User Cookie—
request_body.downloadintegerNo是否下载/Download: 0=不下载, 1=下载0
request_body.end_datestringYes结束日期(格式YYYY-MM-DD)/End date (format YYYY-MM-DD)—
request_body.start_datestringYes开始日期(格式YYYY-MM-DD)/Start date (format YYYY-MM-DD)—
request_body.need_livingintegerNo是否包含正在直播的场次/Include living rooms: 0=不包含, 1=包含1

Invocation example

Parameter template

Generated from the parameter configuration. Replace the sample values before use.

POST/agent-api/v1/tool/executeX-Api-Key
Request coderequest.sh
curl --request POST \
  --url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_douyin_fetch_creator_live_room_history_list' \
  --header "X-Api-Key: $AGENTEARTH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "params": {
    "request_body": {
      "cookie": "Your_Cookie_Here",
      "end_date": "2025-10-11",
      "start_date": "2025-09-11"
    }
  }
}'

No response example available yet.