Social data (beta)

/

GET /v1/social/{platform}/{capability} returns public data from Douyin, Xiaohongshu, TikTok, YouTube and other social platforms, with the same API key and balance as your model calls. Each platform and capability is priced per successful call, and data is the platform's own response — fields are not normalized across platforms.

GET /v1/social/{platform}/{capability} 
curl --get "https://api.chinaapi.ai/v1/social/bilibili/search" \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  --data-urlencode 'keyword=Python'

# HTTP 200
# {"object": "social.result", "platform": "tiktok", "capability": "search", "data": {...}}
Beta: paid accounts only Complete your first top-up before calling. Trial credit cannot be spent on these endpoints; an account that has never topped up gets HTTP 403 model_requires_topup. The beta has no SLA, and its platforms, endpoints and prices may change.

Authentication and billing

Send your ChinaAPI key as a bearer token to https://api.chinaapi.ai, as for any model call. A call is charged once, at the price listed for its endpoint, only when it returns HTTP 200 with data; an empty result, a rejected parameter or a failed upstream costs nothing. Every page you fetch is a separate call. Your usage log lists each call under the name shown with its endpoint, such as social-douyin-search.

Responses and errors

A successful response wraps the platform's data in a small envelope. Everything inside data — field names, pagination cursors, IDs — is the platform's own; pass cursors back exactly as you received them.

{
  "object": "social.result",
  "platform": "douyin",
  "capability": "search",
  "data": { "...": "the platform's own fields" }
}
  • 400 — a parameter is unknown, repeated, too long, of the wrong type or missing, including when no member of an "at least one of" group is given. The error code says which, such as unknown_parameter or missing_parameter.
  • 403 model_requires_topup — the account has not completed its first top-up.
  • 404 — the platform and capability pair does not exist, or the platform found nothing for these parameters (social_data_no_result).
  • 429 social_data_capacity_reached — the beta's capacity for the day is used up and resets at 00:00 UTC, or the platform is busy and a retry a few seconds later will do. Do not retry in a tight loop.
  • 502 social_data_no_result — the data source did not answer, or answered without data.
  • 503 social_data_unavailable — this endpoint is paused right now; the live catalog lists it as paused.

None of these responses is charged.

LinkedIn asynchronous tasks

The post-async, user-async and company-async capabilities use POST, query parameters and an empty body. Supply an Idempotency-Key (8–128 characters) unique to your intended operation. Reusing the same key and parameters returns the original submission without another charge; changing parameters under that key returns HTTP 409. A lost response is retried with the same key.

curl --get -X POST "https://api.chinaapi.ai/v1/social/linkedin/company-async" \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Idempotency-Key: company-research-20261029-001" \
  --data-urlencode 'url=https://www.linkedin.com/company/microsoft/'

# HTTP 202 returns a ChinaAPI task id and Location.
curl "https://api.chinaapi.ai/v1/social-tasks/TASK_ID" \
  -H "Authorization: Bearer $CHINAAPI_KEY"

Creation reserves the catalog price. A task with usable records keeps that charge; failure, empty results or timeout refund the reservation. Status and result reads are free, require the same account, and do not create another task. Poll no faster than every five seconds. Results are available for 30 days; do not submit another paid task just to read the same result. submission_pending means the submission outcome is uncertain: keep the same key and contact support if it persists.

These asynchronous capabilities are available through REST. The data MCP fetch tool lists synchronous capabilities only.

Xiaohongshu creator hot topics

GET /v1/social/xiaohongshu/creator-hot-topics returns the creator center’s hot inspiration feed. This is a separate capability, not a platform-wide trending ranking; the old trending endpoint remains unavailable. The live catalog lists its per-call price.

Leave cursor empty on the first request. Pass the response’s data.data.cursor unchanged to fetch the next page; items are in data.data.items. Stop when data.data.end_flag is true, a cursor repeats, or a page has no new items. Each successful nonempty page is billed separately. Empty results and business errors are not charged.

Telegram public channels

Telegram user returns a public channel profile, post returns one channel post, and user-posts returns channel posts. These endpoints do not retrieve personal account profiles or private chats. Pass channel=durov; a post also needs its post_id. Comments remain unavailable.

For user-posts, limit is 1–100 (upstream default 20). Fetch older posts with the preceding response's data.pagination.before_cursor as before; fetch newer posts with data.pagination.after_cursor as after. Choose one direction per request. Read posts from data.messages, deduplicate by post ID, and stop on an empty page, repeated cursor, no new IDs or your page/spending limit. has_more_before=false ends backward collection. Each nonempty successful page is billed separately; unavailable previews and empty results are not charged. Media links can expire.

Search implementation changes

TikTok search uses the App V3 implementation with keyword, offset, count, sort_type and publish_time. Start at offset 0; the former Web search_id is not supported. Returned data retains App V3 fields. Threads search returns top results and supports no pagination; results can vary by query and retrieval time. These path changes keep the previous per-call prices.

Pagination and bounded collection

Douyin comments and comment replies use the App V3 cursor contract. Start with cursor=0 and count=20; only count 20 is supported. Comment replies require both item_id (video ID) and comment_id (parent comment ID). Pass the returned cursor unchanged within the same capability. Old Web cursors cannot be reused.

Pages can overlap even when the cursor advances. Deduplicate by cid, stop when has_more is false, when a cursor repeats, or when no new IDs arrive; set a maximum page count and a spending limit. Each successful page is separately billed, including overlapping items. An empty page returns an uncharged no-result error and should end collection.

Threads comments and top search currently support the first page only. Sending a nonempty end_cursor is rejected before billing. Do not interpret a first-page response as a complete comment history. For every platform, use only the pagination parameters advertised in the live catalog.

Acceptable use

Follow each platform's terms and the data-protection rules that apply to you. Do not use this API to build profiles of individuals. Logging in, extracting contact details, manipulating engagement and reaching private or paid content are outside this beta.

Platforms and prices

USD per successful call. Each price links to its endpoint below, and a dash means the platform does not offer that capability. The live catalog — GET https://dash.chinaapi.ai/api/social/catalog, no key needed — is the authority on what is on sale right now, including any endpoint that is paused.

Endpoints

Parameters go in the query string under the platform's own names. Examples come from the catalog; replace identifiers with the content you want to retrieve.