Zhihu Expert Discovery API: Candidate Search or a Known Profile

Use one Zhihu user search or profile request, preserve exact URL tokens and unknown fields, and avoid treating follower counts as expert qualifications.

Historical Zhihu expert discovery concept with fictional search, profile, answers and agent cards

A keyword search can return twenty accounts with similar names and still leave the important decision unresolved: which person did you mean? A Zhihu expert discovery API integration should make that choice visible. This guide reads one page of candidate accounts or one profile whose URL token you already know. It stops before choosing an expert, collecting answers, or turning follower counts into a qualification score.

The November 8, 2026 revision checks current endpoint contracts and replays saved public examples offline. It makes no new business request. The September 27 article’s three-step design remains archived; the October 7 search and profile samples below are independent records, not a newly tested chain. The Zhihu API hub covers other capabilities separately.

Key takeaway

  • Choose zhihu/web/user-search-v3 for keyword candidates, or zhihu/web/user-info for one intentionally selected profile.
  • Search limit and offset are strings. A profile uses object.url_token, not a search-hit number, internal account hash, or highlighted name.
  • Require a completed SandBase envelope and an object at outputs[0].data; search has a data array, while the profile is flat.
  • Counts and badges are observations about an account. They do not independently establish expertise, measured reach, or permission to contact it.

The retained cover illustrates the old search → profile → answers → agent concept. Its fictional AI_Scholar account, figures, badges, and answer cards are design elements, not a customer, a measured result, or evidence that the current example executes that sequence.

Choose one Zhihu expert discovery API task

What you haveSelected APIFirst request
A topic or account keywordWeb User Search V3keyword, explicit limit: "5", offset: "0"
A deliberately selected profile slugWeb User Infouser_url_token, such as ming-he-43-93

Only keyword is required for search. The inspected schema defaults are string "25" for limit and string "0" for offset, with no declared numeric bounds. Five is a local teaching choice to request a small first page, not a guarantee of five returned accounts. The saved request supplied only keyword: "deepseek"; its twenty results do not show that this new five-item request was executed.

The profile route takes one required string. Keep the web/ path: similarly named routes can have different parameters and prices. If you already have a profile URL, take its /people/ slug deliberately. Do not let an agent pick the first name match just to fill that parameter.

Historical User Search V3 keyword and string paging parameter reference Historical User Search V3 parameter reference: required keyword and optional string limit/offset, with 25/0 defaults. It shows a placeholder response envelope, not a search-and-profile execution or twenty returned people.

Set up your key or hand the task to an agent

Already have a SandBase key? Reuse SANDBASE_API_KEY from your local environment or secret manager. Already connected an agent? Give it the selected route, keyword or token, and a one-request budget; it need not create another key or rebuild the integration. For a new project, use the setup Skill with the Markdown quickstart. The human quickstart explains the account setup.

A useful instruction is: “Read the setup Skill. Use my existing local key to fetch one Zhihu keyword candidate page for deepseek. Return exact profile tokens and raw available counts, report skipped records, and stop before selecting a profile or requesting answers.” For a known profile, replace the task and input explicitly. Do not paste a key into the instruction, article, issue, or chat transcript.

Install the Python dependency with python3 -m pip install requests, save the code below as a local file, and set the environment variable outside that file. Authentication goes to SandBase. No Zhihu password or OAuth credential is an input to these two selected routes; that does not imply access to private content.

One request with an explicit stop

This uses the Model API POST /v1/api/zhihu/web/<route>, not a catalog GET or /v1/run. It reads only the documented outputs[0].data. The two reference payloads do not have a business code, status, or success field, so borrowing a code-zero check from another provider would reject good data.

Python
import os
import requests


def first_request(task, value):
    if not isinstance(value, str) or not value.strip():
        raise ValueError("Supply a nonblank keyword or an explicitly selected token")
    if task == "search":
        route = "user-search-v3"
        params = {"keyword": value, "limit": "5", "offset": "0"}
    elif task == "profile":
        if any(c.isspace() or c in "/?#" for c in value):
            raise ValueError("Use the profile slug, not a URL or display name")
        route = "user-info"
        params = {"user_url_token": value}
    else:
        raise ValueError("Choose search or profile")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise ValueError("Set SANDBASE_API_KEY locally")
    try:
        response = requests.post(
            "https://api.sandbase.ai/v1/api/zhihu/web/" + route,
            headers={"Authorization": "Bearer " + key},
            json=params, timeout=(10, 90), allow_redirects=False,
        )
    except requests.RequestException:
        raise RuntimeError("Request failed; no automatic retry was made") from None
    if not 200 <= response.status_code < 300:
        raise RuntimeError("HTTP request rejected: " + str(response.status_code))
    try:
        body = response.json()
    except ValueError:
        raise RuntimeError("Response was not valid JSON") 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 documented outputs[0].data")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Expected a business object at outputs[0].data")
    # These references have no business code/status/success field.
    if task == "search":
        rows = payload.get("data")
        if not isinstance(rows, list):
            raise RuntimeError("Search data must be an array")
        people, skipped = [], 0
        for row in rows:
            if not isinstance(row, dict):
                raise RuntimeError("Malformed search row")
            user = row.get("object")
            if user is not None and not isinstance(user, dict):
                raise RuntimeError("Malformed search object")
            if not user or user.get("type") != "people":
                skipped += 1
                continue
            token = user.get("url_token")
            if not isinstance(token, str) or not token.strip():
                skipped += 1
                continue
            people.append(user)
        return {"payload": payload, "people": people, "skipped": skipped}
    if payload.get("url_token") != value or not isinstance(payload.get("name"), str):
        raise RuntimeError("Profile identity or flat reference shape did not match")
    if not payload["name"].strip():
        raise RuntimeError("Profile name is missing")
    return {"payload": payload}


if __name__ == "__main__":
    result = first_request("search", "deepseek")
    print(len(result["people"]), "usable candidates; skipped", result["skipped"])

To read the known profile instead, replace both final indented lines with result = first_request("profile", "ming-he-43-93") and print(result["payload"].get("name"), result["payload"].get("follower_count")). Do not append a second call after the search. The token checks are local guards against empty values and accidentally pasted URLs, not a claim about every possible upstream identifier.

The returned people and skipped keys are local conveniences, not provider fields. Unrecognized row objects and people without usable tokens are counted as skipped; malformed scalar rows or scalar objects stop the program. An empty data array is valid. Optional metrics stay absent, null, or zero as received. The helper checks a profile’s exact selected token and a nonblank name; a missing identity or error-only object cannot become an empty successful profile.

There is no automatic retry, next page, first-hit selection, answer lookup, avatar download, or messaging action. Errors report the failure class rather than printing the bearer key or a raw provider error body. Redirects are rejected before credentials can be forwarded elsewhere. A timeout means the client stopped waiting, not proof that no upstream work occurred; inspect the account before deciding whether another request is appropriate.

Read the saved search without changing its meaning

The public saved search 3aae9ba3-8312-4f08-819d-2d8841824798 is dated 2026-10-07T17:36:49.471Z, with input {"keyword":"deepseek"}. Its full captured payload has twenty search-result rows, all containing people objects and string URL tokens. That observation does not guarantee that future searches cannot contain other record types. This exact projection of the first saved row omits media, badge metadata, and opaque session fields:

JSON
{
  "id": 4029889030,
  "type": "search_result",
  "hit_labels": null,
  "object": {
    "type": "people",
    "id": "b2be5c4564dd15544180d35da0500188",
    "url_token": "deepseek-75",
    "name": "<em>DeepSeek</em>",
    "headline": "",
    "answer_count": 0,
    "articles_count": 2,
    "creation_count": 2,
    "follower_count": 58778,
    "follower_count_text": "5.8 \u4e07"
  }
}

Three identifiers coexist here. The numeric row id identifies a search hit. The string object.id is an internal account hash. The profile task needs object.url_token. A display name can contain <em> markup and can be shared by several accounts. Keep it as text; use escaped text rendering or remove known highlight formatting rather than inserting arbitrary HTML into a dashboard.

The first saved account has 58,778 followers, while follower_count_text is the localized display string 5.8 万. Store both if the UI needs both; do not replace the exact number with a guessed conversion. Zero answers, an empty headline, a null hit label, and an absent field mean different things. A candidate table should expose unknown values instead of silently filling them with zero.

The separately trimmed README shows four articles and four creations for its first result; the full saved capture shows two and two. Another README count example is 1,147 answers, 32 articles, and 5,788 creations; the saved second record has 1,119, 31, and 5,626. These are different references, not a measured growth series. Creation totals also need not equal answers plus articles. Comparing them as if they were a single synchronized measurement would manufacture a trend.

Why the next-page URL does not justify a loop

The saved page reports paging.is_end: false. Its upstream paging.next URL contains limit=20 and offset=20, plus query and opaque context. That differs from assuming the schema’s omitted limit always produces twenty-five results. The saved example alone cannot resolve that difference.

Do not increment by twenty or twenty-five unconditionally. Do not follow the upstream URL with your SandBase bearer key, and do not copy search hashes, session parameters, attached_info_bytes, or the unresolved captured ab_params: "$1d" into a request. They are not inputs to this selected schema. A future continuation implementation needs a separately verified mapping back to the declared string limit/offset, the same keyword, and the returned end condition. This revision has not tested that roundtrip or whether discarding upstream context changes results.

For this task, preserve paging metadata alongside the observed page and stop. “Twenty candidates observed” is a useful output; “all experts found” is not supported by it.

Read a known profile without joining unrelated examples

The saved profile efd5baa5-aefb-48e6-9013-9f66dddde8ee is dated 2026-10-07T17:36:12.157Z, for user_url_token: "ming-he-43-93". That token does not occur among the saved search’s twenty people. The following exact field projection belongs to an independent profile request:

JSON
{
  "url_token": "ming-he-43-93",
  "type": "people",
  "follower_count": 2830,
  "follower_count_text": "2830",
  "follower_count_num": "2830",
  "follower_count_unit": "",
  "answer_count": 9,
  "articles_count": 87,
  "ip_info": "IP \u5c5e\u5730\u672a\u77e5",
  "allow_message": true,
  "is_realname": true,
  "is_org": false,
  "org_verify_status": null,
  "employments": []
}

Historical Web User Info profile token parameter reference Historical Web User Info reference: the required user_url_token and the documented outer envelope. The generic “User ID” label should be read as the profile URL slug for this route; the screenshot’s empty example does not prove any business count.

The payload is already the profile. There is no data.user layer to unwrap. Its follower count is 2,830, answers nine, and articles eighty-seven in this saved record. The text/num display fields happen to be "2830" with an empty unit, but that is not a universal lossless conversion rule.

The location text explicitly says location unknown. Empty employment and badge lists, null organization verification and assistant fields, and an undocumented numeric gender code should remain uncertain rather than becoming demographic or affiliation guesses. Returned is_realname, is_org, and allow_message flags are not independent credential checks or authorization for outreach. Avatar and profile links stay references; this example neither downloads media nor follows account graphs.

A useful research record keeps the selected token, request purpose, observation time, raw available fields, and a separate human assessment of topical relevance. Follower and answer counts can describe account activity; they do not measure unique audience reach or certify the quality of an answer. Additional answer evidence would require a separately checked endpoint and an explicitly chosen task.

What remains from the September article

The September 27 version proposed search → profile → answers and included the following illustrative envelope. It was labeled illustrative, not a verified dated answers run; the ID must not be reused as proof of the October examples or a November call:

JSON
{
  "id": "876962b1-9b17-409f-a654-4a5004199e31",
  "status": "completed",
  "model": "zhihu/web/user-answers",
  "outputs": [
    {
      "data": {
        "data": [
          { "answer_type": "…", "content": "…", "comment_count": 0 }
        ]
      }
    }
  ]
}

Historical User Answers string pagination and sort parameter reference Historical User Answers parameter reference, retained for the original design. It lists string limit/offset and sort_type alongside user_url_token, but its empty response does not demonstrate an answer feed or a continuation. This route was not revalidated in the current two-task revision.

The original bilingual code archive preserves all eight Python blocks, the original text, and hashes. It is historical material, not the recommended runnable path. The old helper could turn missing data into {}, then pass a missing first result into a profile call. Its instructions also conflicted about incrementing offsets versus reading response paging. Those behaviors have been replaced here rather than hidden behind a fallback.

The old multi-keyword expansion, ranking by follower/answer counts, scheduled retries, and “full feed” or reach-growth claims were design suggestions without current supporting experiments. This revision does not certify their contracts, cost, coverage, or success. For question-centered research instead, see the separate Zhihu question and answers guide.

Cost and failure decisions

The November 8 inspection lists both selected web routes at $0.001 each, eligible for the organization’s shared allowance of 100 daily calls across eligible APIs, resetting at 00:00 UTC. Eligibility is not a checked remaining balance or a promise that this request will be free. Deliberately choosing both tasks lists at $0.002 before quota effects; the code executes only one. No new charge was measured in this revision, and failure-billing behavior was not independently retested.

For 401/403, check key configuration and access without printing secrets. For 429, stop and inspect allowance or limits before planning another attempt. For invalid JSON, incomplete status, unexpected business shape, or mismatched profile identity, keep the failed observation separate from an empty result. A green HTTP status alone cannot establish that the chosen account was returned.

FAQ

Can the agent automatically choose the best expert? The current task produces candidates or a selected profile snapshot. Expertise requires contextual evidence; a matching name, badge, or large count is insufficient.

Which identifier should I pass to Web User Info? Use a deliberately selected object.url_token or the slug from a known profile URL. Numeric search-hit IDs, internal hashes, and names are different fields.

Why are limit and offset quoted? The current selected schema declares strings. Defaults are "25" and "0"; the saved keyword-only twenty-row page does not validate a fixed-size increment.

Does an empty candidate list mean no suitable people exist? No. It describes that observed page, or the locally recognized subset when skipped is nonzero. Inspect the distinction before drawing a conclusion.

Does allow_message mean I may contact the account? No. It is a returned flag, not user authorization to send messages. The example stops after its read.

Found this useful? Share it