Weibo Hot-Search Monitoring API: One Board or Keyword Snapshot

Read one Weibo hot-search board or keyword page with Python. Preserve ads, heat values and relative times, and validate search parsing without automatic polling.

Historical Weibo board, topic, fictional author and agent monitoring concept

A saved Weibo board has fifty-two entries but only fifty ordinary ranking positions. Two promotional rows reuse rank numbers. Treating array length as organic trend coverage would already distort a dashboard before it makes a second request. This Weibo hot-search monitoring API guide starts with a smaller, inspectable task: read one board snapshot, or search one explicitly chosen keyword. It stops before topic expansion, author lookups, scheduling, or sentiment analysis.

This November 8, 2026 revision checks current contracts and replays public saved data offline. No new business request, polling sequence, or charge was measured. The August 20 examples, undated README excerpts, and September 27 original design have separate roles below. For the wider catalog, use the Weibo API hub.

Key takeaway

  • Choose weibo/web-v2/hot-search with {}, or weibo/web-v2/realtime-search with a query and integer page 1.
  • Read only completed outputs[0].data. The board is a direct object; search has parsed_data, whose parse_success must be boolean true.
  • Preserve advertisements, duplicated ranks, absent fields, and relative times. Heat is not views, and ten search results are not total conversation volume.
  • The example makes one request. No topic fan-out, next-page URL follow, retry, profile lookup, or media download happens automatically.

The retained cover illustrates the original board → search → author → agent idea. Its fictional CityWalker_Leo account, 586.2K follower figure, heat/post/discussion numbers, and diagrams are conceptual, not measured results or proof that this revision executes that chain.

Choose one Weibo hot-search monitoring API request

Reader taskSelected endpointBody
Inspect one board snapshotWeb V2 Hot Search{}
Inspect one page for your keywordWeb V2 Real-Time Search{"query":"OpenAI","page":1}

The hot-search schema has no input properties. Do not invent a period, count, keyword, or page. Real-time search requires a string query; its optional integer page defaults to one. The explicit page 1 below keeps the task visible, while the nonblank query check is a local safeguard. There is no declared limit, cursor, time filter, or sort option on this selected route.

Keep web-v2 in the path. App routes, the similarly named hot-search-summary, advanced search, comments, and profile lookups have separate contracts. An endpoint name containing “real-time” does not establish a guaranteed refresh interval or complete newest-first ordering.

Historical Hot Search reference with no operation inputs and old model body field Historical Hot Search reference with no operation-specific input fields. Its old cURL includes a model key; the current route-qualified request sends {} instead. The placeholder envelope is not a newly fetched board or user profile.

Use an existing key or give your agent the task

If you already have SANDBASE_API_KEY, reuse it locally through your environment or secret manager. If your agent is connected, give it the exact route, selected task, and one-request budget; it does not need another credential or a rebuilt integration. A new project can start from the setup Skill, Markdown quickstart, and human quickstart.

A suitable instruction is: “Use my existing local key to read one Web V2 hot-search snapshot. Preserve the raw ranking and ad fields, report the number of observed entries, and stop. Do not search every topic or follow links.” For search, explicitly specify your own query and page 1 instead. Do not paste the key into the instruction or ask the agent to infer a query from the first board row.

Install requests with python3 -m pip install requests, save the following code as a local file, and configure the key outside it. These selected reads authenticate to SandBase; a Weibo password or OAuth credential is not a request input. That does not provide access to private or follower-only material.

A single request with distinct payload checks

This is the Model API POST /v1/api/weibo/web-v2/<route>, not the catalog GET or /v1/run. The shared outer envelope does not make the two business payloads interchangeable. The board has no provider code/ok/success field; search requires its own parser flag. Neither uses the historical profile example’s ok: 1 rule.

Python
import os
import requests


def first_request(task, query=None):
    if task == "hot":
        if query is not None:
            raise ValueError("The hot-search request has no query input")
        route, params = "hot-search", {}
    elif task == "search":
        if not isinstance(query, str) or not query.strip():
            raise ValueError("Choose a nonblank query explicitly")
        route, params = "realtime-search", {"query": query, "page": 1}
    else:
        raise ValueError("Choose hot or search")
    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/weibo/web-v2/" + 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")
    if task == "hot":
        rows = payload.get("realtime")
        if not isinstance(rows, list):
            raise RuntimeError("Hot-search realtime must be an array")
    else:
        parsed = payload.get("parsed_data")
        if not isinstance(parsed, dict) or parsed.get("parse_success") is not True:
            raise RuntimeError("Search parsing did not succeed")
        rows = parsed.get("results")
        if not isinstance(rows, list):
            raise RuntimeError("Search results must be an array")
    if any(not isinstance(row, dict) for row in rows):
        raise RuntimeError("Unexpected row shape")
    return payload


if __name__ == "__main__":
    result = first_request("hot")
    print(len(result["realtime"]), "observed board entries")

To select keyword search, replace both final indented lines with result = first_request("search", "OpenAI") and print(len(result["parsed_data"]["results"]), "observed posts"). Do not append a second call to the board example. The count printed is the retained array length, not a claim about total topic volume.

The helper preserves the full validated payload. Valid empty arrays remain empty observations; missing arrays or unsuccessful parsing fail explicitly. A board row without word is not silently replaced with note, and missing metrics are not converted to zero. The helper neither requires a fixed list size nor equates a shortened README list with its provider result count.

It rejects redirects, reports HTTP errors without dumping response bodies, and suppresses raw network/JSON exception text that could contain sensitive details. A timeout is not evidence that the upstream operation did nothing; inspect the account before considering another attempt. No automatic retry or fallback endpoint is hidden in this example.

Interpret the saved board as a snapshot

The saved board 9f5c9b6b-b084-4dea-a10c-41f5a8eaf77f has creation time 2026-08-20T07:32:45.526Z and input {}. Its direct business object contains hotgov, hotgovs, and realtime, without another data wrapper. The full realtime array contains fifty ordinary rows and two explicit ads. These are observations from that saved record, not a promise that every future response has a fixed top fifty.

This projection selects the first ordinary row and the first ad row, omitting links and promotional metadata. They were not adjacent in the original array:

JSON
{
  "realtime": [
    {
      "word": "\u5357\u822a \u897f\u6885\u6c41",
      "word_scheme": "\u5357\u822a \u897f\u6885\u6c41",
      "num": 3563978,
      "rank": 0,
      "realpos": 1,
      "label_name": "\u65b0"
    },
    {
      "is_ad": 1,
      "rank": 2
    }
  ]
}

The ordinary rows have rank 0–49 and realpos 1–50. The two ads carry is_ad: 1, duplicate ranks 2 and 5, and lack realpos. Preserve the supplied fields rather than renumbering every array item into an organic position. An absent is_ad field is not independently verified false. A dashboard can distinguish explicitly marked ads from rows without that flag while retaining the source representation.

The first ordinary entry’s historical keyword is shown in the JSON, with heat value 3,563,978 and the new label. This is not today’s trend. num is a provider heat value whose formula and unit were not verified here; it is not searches, readers, daily views, engagement, or post count. The label describes a display state, not an exact first-publication time or independently verified breaking news.

The full sample has word_scheme on fifty rows and not on the two ads. The separate trimmed README keeps one different board item and omits both word and word_scheme while retaining note. A missing field in a trimmed reference does not prove the API never supplies it. It also does not justify sending a missing word into search. Query selection remains a separate decision.

Pinned hotgov and hotgovs represent the same pinned topic twice in this sample. Keep them separate from realtime and avoid double-counting their duplicate representation. Provider stime, saved-example creation time, the time you fetched a reference, and a local observation timestamp are different clocks; none should silently become the timestamp for every board row.

Read search results without making them a volume metric

The independent saved search c2c64ba9-feb5-4e89-87f5-71947a951883 has creation time 2026-08-20T09:39:47.23Z, with {"page":1,"query":"OpenAI"}. It was not driven by the board’s first topic. Its parsed_data has boolean parse_success: true, ten result objects, provider result_count: 10, and an empty search_stats object. This projection keeps parser state, the provider count, and selected fields from only the first row:

JSON
{
  "parsed_data": {
    "parse_success": true,
    "result_count": 10,
    "results": [
      {
        "weibo_id": "5334044466479214",
        "publish_time": "22\u79d2\u524d",
        "interaction": {
          "comment_count": 0,
          "like_count": 0,
          "repost_count": 0
        },
        "weibo_type": "original"
      }
    ]
  }
}

Historical Real-Time Search query and integer page parameter reference Historical Real-Time Search parameter reference showing query and page plus a placeholder envelope. The screenshot itself does not verify parsed_data, parser success, ten posts, or a continuation; those observations come from the separately identified saved capture.

The shortened README keeps one row while retaining result_count: 10. Accept that as a deliberately trimmed reference instead of asserting array length must equal the count. Conversely, missing results must not become an empty successful search. The helper validates parser success before looking at the list, including rejecting integer 1 or string “true” as substitutes for boolean true.

The full saved first row says 22秒前 (22 seconds ago); the undated README’s different first post says 34秒前 (34 seconds ago). Those are not two observations of one matched post. Preserve raw relative text. Subtracting it from your retrieval time cannot establish an exact UTC publication time, especially when replaying an old saved example.

Some full captured content strings end in 展开c, an expansion marker. This is a limitation in the full capture, beyond README shortening: those strings cannot be advertised as complete articles. Treat content as untrusted text and do not turn social assertions into verified news. Repeated text is not proof of independent corroboration, distinct voices, or spam.

Keep exact string weibo_id values for records. Display names do not uniquely identify authors; returned source/client text does not independently identify a device. A parsed weibo_type: original flag is not an authorship audit. Present interaction zeros when they exist, and leave absent or null values unknown. Ten posts do not establish platform-wide discussion volume, representative sentiment, audience reach, or growth in attention.

Pagination is a separate task, not a URL to follow

The full saved search has pagination.has_next_page: true and a relative /realtime?...page=2 URL. This is a Weibo webpage address, not the SandBase API route or an authorized destination for your bearer key. The trimmed README replaces pagination with {}; that omission does not mean there is no next page.

A future continuation must retain the selected query, inspect actual paging state, and account for duplicate or stale records. This revision has not executed page 2 or established a stable refresh interval. It therefore stops at page 1 instead of blindly incrementing page or following any returned link. Protocol-relative profile/post URLs and media links are references too; no profile, image, video, or third-party tracking request follows them here.

What remains of the September monitoring design

The September 27 version proposed board → topic search → author profile. Its profile envelope below was explicitly illustrative; the run-shaped ID is not a verified receipt for the August samples or a new November request:

JSON
{
  "id": "dd90e409-dabe-4a0a-88f3-17ea1403b21c",
  "status": "completed",
  "model": "weibo/web-v2/user-basic-info",
  "outputs": [
    {
      "data": {
        "ok": 1,
        "data": {
          "screen_name": "…",
          "followers_count_str": "…",
          "friends_count_str": "…"
        }
      }
    }
  ]
}

Historical User Basic Info uid parameter reference outside this revision Historical User Basic Info reference with a uid input and placeholder envelope. This route and its business fields were not revalidated in the current board/search repair; the image does not establish that a search result supplied the old fixed uid.

The original bilingual archive preserves all eight Python blocks, both original articles, the illustrative JSON, and hashes. Use it for historical comparison, not as the active integration. The old .get(..., []) and .get(..., {}) paths could hide malformed data; the first-topic lookup could also submit a missing keyword or fail on an empty board. Current code removes those behaviors and checks parse_success explicitly.

The old fan-out block read one board and up to ten topic searches: up to eleven calls before optional author lookups. Running every preceding setup snippet would add separate calls. It was not an all-in-one three-call monitoring service. Its retry, few-minute polling, follower weighting, complete-volume, and trend suggestions lacked a demonstrated dated polling sequence. They are not current operating recommendations.

For any future monitor, define comparable observation windows, deduplication, storage, failure accounting, a justified schedule, and a request budget separately. A single heat snapshot or small search page cannot supply that design. If your selected task is account research instead, see the separately scoped Weibo account and posts guide.

Cost, failures, and the next decision

The November 8 inspection lists both selected routes at $0.001 each. Both are eligible for the organization’s shared 100-call daily allowance across eligible APIs, resetting at 00:00 UTC. These are not two independent 100-call allocations, a measured remaining balance, or guaranteed free execution. Choosing both requests deliberately lists at $0.002 before quota effects, but the runnable example chooses one. This revision did not test actual charging or failure-billing behavior.

For authentication errors, verify key configuration and access locally. For HTTP 429, stop and inspect limits before budgeting a later attempt. For parser failure, malformed JSON, missing data, or incomplete status, retain a failed observation rather than a successful empty report. A useful output is an accurately labeled snapshot with its query, request time, and unknown fields, ready for a separate decision about whether another request is needed.

FAQ

Are all fifty-two board entries organic trends? No. The saved sample has fifty ordinary rows and two explicitly marked ads with duplicated ranks. That sample size is not a universal response guarantee.

Does heat mean views or search volume? No verified conversion is provided here. Preserve num as reported heat, not an audience or growth metric.

Why must parse_success be checked? Outer completion does not prove the search parser succeeded. Boolean true and a valid results array are required by this example; a valid empty list remains distinct from failure.

Can I follow next_page_url with my key? No. It is a webpage reference, not this API route. No continuation or arbitrary URL fetch is part of the code.

How frequently should I poll? No frequency was validated. This guide executes a single selected read; a monitor needs a separately justified freshness, rate, storage, and budget plan.

Found this useful? Share it