Kuaishou Creator Research API Tutorial | SandBase

Search one Kuaishou candidate page or read one known creator profile, validate endpoint-specific status, and preserve unknown counts with one bounded request.

Dark cinematic render of a Kuaishou user search resolving into a creator profile card, feeding an agent core

A creator search and a creator lookup answer different questions. A keyword gives you candidates; a known account ID lets you inspect one account. Mixing them into an automatic loop makes a first integration harder to debug and can multiply requests before you have checked whether the candidates are relevant.

This guide repairs the existing Kuaishou creator-research tutorial on 2026-11-08 using free inspect and public reference captures. It makes no new business request. The original 2026-09-28 UTC experiments remain historical observations. Start with one of the two tasks below; use the Kuaishou API hub for the broader catalog.

Key takeaway

  • Search one page with keyword and an explicit empty pcursor; inspect candidates without automatically choosing one.
  • If you already know the numeric user_id, call the profile route directly. A display name, handle and account ID are not interchangeable.
  • Read completed outputs[0].data. Search checks integer responseCode: 0; profile checks integer result: 1 and the nested profile structures.
  • Each selected endpoint is listed at $0.01 and is eligible for a shared daily quota. Eligibility does not tell you how many free calls remain.

The retained cover is conceptual artwork: its handles, 1.28M followers, 46.7M likes and video counts are fictional illustration labels, not API measurements or verified creators. It does not promise automatic creator selection.

Choose the request you need

What you haveTask and destinationParameters in this example
A topic or creator name to investigateUser search V2keyword, pcursor: ""
A known numeric account IDSingle user V2user_id as a string

The search schema also exposes fans_sort, user_gender and user_relation. Its enumerated choices include follower sorting, gender and relationship filters. The short example deliberately omits them: it does not assume a default filter or pretend to test every combination. A verified-account filter is a search option, not independent proof of identity, audience quality or suitability for a campaign.

Use Kuaishou’s official channels for posting, account-authorized actions or partner integrations. This guide is for public, read-only records through SandBase and still requires a SandBase key. It does not confer access to private posts, private account pages or a person’s messages.

Historical SandBase Kuaishou catalog Historical catalog screenshot retained from the original article. It is navigation context, not evidence of today’s endpoint count, remaining quota or a newly successful request. Its From $0.001 hot-list label is not the current $0.01 price of either selected creator route.

Connect from your current starting point

If you already have a SandBase key, configure SANDBASE_API_KEY in the local runtime or secret manager used by your project. Do not paste the key into an agent chat, article, commit or screenshot. An authentication error is a reason to inspect that environment, not to create another account automatically.

If your agent is already connected, give it the chosen task and the exact route. Ask it to reuse the existing credential configuration, make one request, validate the response and show which fields are present. Do not ask it to “research every creator” until you have reviewed the first result and the request budget.

For a new project, give the agent SKILL.md and quickstart.md, followed by a concrete instruction: “Search one page for my keyword; do not fetch profiles or paginate.” For a known account, replace that task with “Read this user_id once.” The human quickstart explains the setup. Install requests in the Python environment you will actually run.

One checked Python request

This helper has two explicit choices and sends only one POST. It stops on malformed data instead of turning an integration error into an empty creator list.

Python
import os
import re
import requests


def first_request(task, value):
    if task not in ("search", "profile"):
        raise ValueError("Choose search or profile")
    if not isinstance(value, str) or not value.strip():
        raise ValueError("Supply a nonempty string")
    if task == "profile" and not re.fullmatch(r"[0-9]+", value):
        raise ValueError("user_id must be a numeric string, not a handle or URL")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set SANDBASE_API_KEY locally")
    path = "search-user-v2" if task == "search" else "one-user-v2"
    params = {"keyword": value, "pcursor": ""} if task == "search" else {"user_id": value}
    try:
        response = requests.post(
            f"https://api.sandbase.ai/v1/api/kuaishou/app/{path}",
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json=params, timeout=(10, 90), allow_redirects=False,
        )
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"HTTP {response.status_code}; inspect access and budget before retrying")
        body = response.json()
    except ValueError:
        raise RuntimeError("Response was not valid JSON") from None
    except requests.RequestException:
        raise RuntimeError("Network request failed; no automatic retry") from None
    if not isinstance(body, dict) or body.get("status") != "completed":
        raise RuntimeError("SandBase request did not complete")
    outputs = body.get("outputs")
    if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
        raise RuntimeError("Missing outputs[0]")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Missing business object at outputs[0].data")
    if task == "search":
        if type(payload.get("responseCode")) is not int or payload["responseCode"] != 0:
            raise RuntimeError("Search business status was not responseCode 0")
        feeds = payload.get("mixFeeds")
        if not isinstance(feeds, list) or any(
            not isinstance(feed, dict) or not isinstance(feed.get("user"), dict)
            for feed in feeds
        ):
            raise RuntimeError("Expected mixFeeds array with user objects")
    else:
        if type(payload.get("result")) is not int or payload["result"] != 1:
            raise RuntimeError("Profile business status was not result 1")
        profile = payload.get("userProfile")
        if not isinstance(profile, dict) or not isinstance(profile.get("profile"), dict):
            raise RuntimeError("Expected userProfile.profile object")
        if not isinstance(profile.get("ownerCount"), dict):
            raise RuntimeError("Expected userProfile.ownerCount object")
    return payload


if __name__ == "__main__":
    result = first_request("search", "人工智能")
    print("Returned fields:", sorted(result))

For a known profile, replace the final assignment with result = first_request("profile", "3795214411") and keep the field-list print. Do not append it as a second automatic call. That ID is the existing public schema example; this repair did not execute it.

The function deliberately returns the original business object. It does not flatten profile fields, rank creators, download avatars, visit shop links or fetch anyone’s videos. It accepts an empty search list as a valid empty result, but it rejects a missing list. Those outcomes have different meanings for a user-facing application.

The profile validation is a guard for the reference structure selected here: userProfile.profile and userProfile.ownerCount must be objects. A response outside that structure needs investigation; the helper does not claim every possible account state will satisfy it. Missing individual counters within an otherwise valid object remain missing rather than becoming zero.

Read search results without losing uncertainty

The public search reference shows mixFeeds entries containing a user object. Candidate identity is not established by list position. A matching display name can belong to a different account, and the returned rank is not evidence that a creator is authoritative or commercially appropriate.

The original experiment recorded run 760a7ea6-b480-40c2-8a91-fb551a2df9c1 on 2026-09-28 UTC, with mixFeeds, pcursor, and observed user fields including user_id, kwaiId, fansCount and following. That historical field list is not a guarantee that every later search returns every field. In particular, do not manufacture an ID from a missing field or decode diagnostic tracking strings as an identity fallback.

A separately saved public example dated 2026-10-07 contains the following trimmed business fragment. Only the first user’s follower count is retained here; identifying text, avatar URLs and tracking data are omitted. This is reference evidence, not a November API run:

JSON
{
  "responseCode": 0,
  "mixFeeds": [{"user": {"fansCount": 89774}}],
  "pcursor": "1",
  "recoPcursor": "no_more"
}

pcursor and recoPcursor are different fields. The search schema describes an empty pcursor for page one and a response-derived pcursor for another page; the recommendation cursor is not a substitute. This repair tests only the first page offline. It does not establish pagination behavior, exhaustion rules or stable results across repeated calls, so the example neither increments a cursor nor loops until a guessed stopping condition.

Historical Kuaishou user search reference Historical search-user-v2 parameter reference. The current example explicitly requests the first page; this screenshot is not evidence of a newly tested next page.

Read the profile at the correct nesting level

The old profile run 142efb32-7caf-47e1-a45e-37cf01c721e2, recorded on 2026-09-28 UTC, observed authorInfo, userProfile and totalPhotoLike. The old code used authorInfo as a fallback for userProfile. That is unsafe: the current reference shows different purposes, not interchangeable representations of a person.

For the selected structure, the account record is under userProfile.profile, and counters are under userProfile.ownerCount. authorInfo holds flags such as verification/business state. Top-level totalPhotoLike can be an entrance/link object; it is not the numeric lifetime-like counter. The counter shown by the reference is userProfile.ownerCount.total_photo_like.

The public full saved profile example dated 2026-10-07 supplies this trimmed fragment. It is kept separate from the older experiment and from this repair’s offline tests:

JSON
{
  "result": 1,
  "userProfile": {
    "ownerCount": {
      "fan": 362287,
      "follow": 2,
      "photo": 674,
      "photo_private": 0,
      "photo_public": 674,
      "total_photo_like": 7199067
    }
  }
}

This is a deliberately partial excerpt, not a complete response you can feed to the strict helper. The saved full example also contains the profile object. Conversely, the short README JSON ends before userProfile; that clipping does not prove that the route cannot return a profile. Keep sample scope attached to any claim about a missing field.

A private-post count does not grant permission or ability to read those posts. A shop entrance, product count or commercial badge is not a sales figure or proof of conversion. An IP-location label is the platform’s displayed account signal, not a precise person-location measurement. Keep these distinctions when designing a report for colleagues who will not inspect the raw JSON.

Historical Kuaishou single-user reference Historical one-user-v2 reference showing the user_id input. The current profile-path explanation comes from public references and a saved example, not a new business execution.

Make comparisons only where the fields support them

A missing follower counter means unknown, not zero. Numeric zero is an observed value; false is a boolean state. Do not replace all three with the same default. Nor should an account with a missing count be ranked below every account with a count: that introduces a ranking decision the data did not support.

Search fansCount and profile ownerCount.fan may describe related signals but come from different requests and times. Record the endpoint and retrieval time before comparing them. A cumulative like total does not measure a recent engagement rate, and a single creator profile does not establish what is typical in a niche. Build a small reviewed shortlist first, then decide whether a separate, budgeted lookup would answer a real remaining question.

The original automatic workflow made one search request plus up to five profile requests: up to six calls, not one. At the current listed unit price that would be up to $0.06 before quota effects. That is an estimate for the old request pattern, not a claim about its historical charge. The new example makes one $0.01-listed request; two separately selected requests would list at $0.02.

Both selected routes are eligible for an organization-shared 100-call daily quota that resets at 00:00 UTC. Other eligible API usage can consume it. This repair did not inspect remaining quota or balance and cannot promise a free successful run. Stop on permission, quota, rate or billing errors and inspect the cause before choosing whether to send another request.

Errors are part of the integration contract

HTTP success is only the transport layer. A completed SandBase run still needs the selected provider-status check: integer responseCode: 0 for search, integer result: 1 for profile. Boolean values and numeric strings are rejected rather than silently accepted as those status codes.

The helper does not follow redirects, retry automatically or include response bodies, request headers or keys in error messages. A timeout leaves the outcome uncertain; blindly resending can create another billable request. Invalid JSON, missing outputs[0].data and incomplete status all stop before field access. Offline tests cover these branches, but they do not prove live service availability.

Historical code and next decisions

The original code is preserved verbatim in the dated archive, with per-block hashes alongside it. It is historical material, not the current integration path: it accepted a top-level output fallback, hid missing data behind empty objects and automatically fetched candidate profiles. The first-request helper above replaces that behavior.

Can I use a handle instead of user_id? The selected profile route requires the numeric account ID as a string. Review a search result’s explicit identity fields; do not assume a name, handle or encoded tracking value is that ID.

Will the agent select the best creator? No. Search returns candidates. Identity, relevance, missing values and your research criteria require a decision before another request or ranking.

Can I paginate or read the creator’s posts? Those are separate tasks. This repair validates one search page or one profile; it does not run continuation requests, a video loop or comment collection.

What should I give my agent? Give it the setup documents, your chosen task and the keyword or known ID. Keep credentials in the runtime. Ask for one checked response and a statement of missing fields before expanding the workload.

Return to the Kuaishou API hub when you need another capability, and verify that endpoint’s inputs, business structure and budget on its own terms.

Found this useful? Share it