Douyin user timeline API

Based on the 2026-10-25 specification snapshot

Quick answer

POST /douyin/users/task with author_id, startDate and endDate (all required, dates as YYYY-MM-DD) starts a task that collects a public Douyin account's posts in that range; max_items defaults to 50 with a ceiling of 1000, and 0 means no item cap. Poll GET /douyin/users/task/{task_id}; once DONE it returns the account ID, a profile object, the timelines and the task metadata. If the secondary timeline backend is temporarily unreachable, the task still completes and the response explains it in error_message. Data is collected by web crawlers from content publicly published on Douyin.

What teams use it for

  • Follow what a brand's official account or a creator posted over a campaign period.
  • Keep a dated record of a public account's videos for research.
  • Compare posting activity across several accounts in one category.

Endpoints

Base URL: https://api.infominer.io/api/v2. Send your API key in the auth-header request header.

MethodPathWhat it does
POST /douyin/users/task Creates a public account timeline task for an account ID and date range, with optional max_items.
GET /douyin/users/task/{task_id} Polls a timeline task; once DONE it returns the profile and the post timeline.

Request parameters

POST /douyin/users/task

ParameterInTypeRequiredDefault / allowedDescription
author_id body string Yes Account ID of the public account.
endDate body string Yes End date (YYYY-MM-DD).
startDate body string Yes Start date (YYYY-MM-DD).
max_items body integer No 50 (max 1000) Maximum posts to collect; 0 means no item cap, bounded only by the crawl page ceiling.

GET /douyin/users/task/{task_id}

ParameterInTypeRequiredDefault / allowedDescription
task_id path string Yes Task ID returned when the task was created.

Response fields

DataFieldsEndpoint
Public account timeline id, profile, timelines, task, error_message GET /douyin/users/task/{task_id}

Code examples

curl: create the task

curl -X POST https://api.infominer.io/api/v2/douyin/users/task \
  -H "auth-header: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"author_id": "0000000000000001", "startDate": "2026-06-01", "endDate": "2026-06-30", "max_items": 200}'

curl: poll the task by ID

curl "https://api.infominer.io/api/v2/douyin/users/task/$TASK_ID" \
  -H "auth-header: YOUR_API_KEY"

Python (requests): create, poll, read

import time
import requests

BASE_URL = "https://api.infominer.io/api/v2"
HEADERS = {"auth-header": "YOUR_API_KEY"}

# 1. Create the task
resp = requests.post(
    f"{BASE_URL}/douyin/users/task",
    headers=HEADERS,
    json={
        "author_id": "0000000000000001",
        "startDate": "2026-06-01",
        "endDate": "2026-06-30",
        "max_items": 200,
    },
    timeout=30,
)
resp.raise_for_status()
task = resp.json()

# 2. Poll until the task leaves INIT / RUNNING
for _ in range(120):
    resp = requests.get(
        f"{BASE_URL}/douyin/users/task/{task['id']}",
        headers=HEADERS,
        timeout=30,
    )
    resp.raise_for_status()
    result = resp.json()
    status = result.get("status") or result.get("task", {}).get("status")
    if status not in ("INIT", "RUNNING"):
        break
    time.sleep(15)
else:
    raise SystemExit("task still running; poll it again later")

if status == "FAILED":
    raise SystemExit("task failed")
if status != "DONE":
    print("task ended with status", status, "- results may be incomplete")

# 3. Read the profile and the timeline
print(result.get("profile"))
timelines = result.get("timelines")
rows = timelines.get("data", []) if isinstance(timelines, dict) else (timelines or [])
print(len(rows), "posts")

Sample response

Illustrative data written by hand: accounts are sample_user_n and IDs are obviously fake. Fields follow the 2026-10-25 specification snapshot; the sample shows a subset, and the full list is in the table above.

Task creation response (illustrative data). The snapshot does not enumerate the fields inside profile and timelines, so confirm them with trial data.

{
  "id": "00000000-0000-4000-8000-000000000001",
  "author_id": "0000000000000001",
  "startDate": "2026-06-01",
  "endDate": "2026-06-30",
  "status": "INIT",
  "tm": 1780272000
}

Limits and notes

  • author_id, startDate and endDate are all required.
  • max_items defaults to 50 with a ceiling of 1000; 0 means no item cap, bounded only by the crawl page ceiling.
  • If the secondary timeline backend is temporarily unreachable, the task is returned as completed with an error_message.
  • How far back timelines go and refresh frequency are confirmed per project scope.
Collection: web crawlers collect content publicly published on each platform. Whether this suits your use depends on the purpose and jurisdiction and is for the buyer's legal team to assess; we can provide a description of sources and collection methods.

More Douyin API pages

Request a trial

In the request form below, mention Douyin and tell us the keywords or accounts, how many comments you need per video, and whether you need video download URLs. We confirm the scope and reply with the arrangements for the trial and API key.

Fill in the form to request a trial. We confirm the scope and reply with trial and integration arrangements.

Fill in the request form

FAQ

How many posts can one timeline task collect?
max_items defaults to 50, with a ceiling of 1000. 0 removes the item cap, leaving only the crawl page ceiling.
Why did a completed task come back with error_message?
The secondary timeline backend was temporarily unreachable. The task is still returned as completed, and error_message says what happened.
Can I collect posts from a private account?
No. Only content publicly published on Douyin is collected.
How is the data collected? Is this the official Douyin API?
By web crawlers, from content publicly published on Douyin. LargitData is not affiliated with Douyin and this is not Douyin's own API. Whether this suits your use depends on the purpose and jurisdiction and is for your legal team to assess; we can provide a description of sources and collection methods.