Weibo Account Post Research API Tutorial | SandBase
Read one known Weibo profile or one page of account posts with checked Python responses, explicit request budgets and dated original-post research evidence.

Researching a Weibo account starts with a smaller question than “rank everything it has ever posted.” Do you need to confirm a known account’s profile, or inspect one page of its timeline? Those are separate requests, with different business responses. Starting with one makes it easier to distinguish an empty result from a failed lookup before building a larger research workflow.
This 2026-11-08 repair checks the current request contracts and public response references for those two tasks. It did not execute a paid business request. The original 2026-10-01 UTC account experiment remains below, including its real run IDs and trimmed profile. Its original-posts pagination and comment workflow have not been revalidated. The Weibo public data API hub covers the broader catalog; hot-search monitoring is a different task.
Key takeaway
- Known numeric UID or custom profile name: make one
user-inforequest with exactly one identifier.- Known UID and a timeline question: make one
user-postsrequest withpage: 1,feature: 0, and nosince_id.- Read only completed
outputs[0].data; profile usesuser, while posts requires integerok: 1anddata.list.- A timeline may contain reposts. One page is neither an original-only feed nor a complete account history.
Choose the first request
| What you already know | Endpoint | Input for this example |
|---|---|---|
| Numeric public account UID | User info | uid only |
| Custom name from a profile URL | Same user-info endpoint | custom only |
| Numeric UID, and you want recent account posts | User posts | uid, page: 1, feature: 0 |
A display nickname is not necessarily a custom profile name or unique identity. If you have only a brand name, first identify the intended account; this example does not search and silently choose the first match. The numeric UID remains a string, so clients do not round large identifiers. The schema describes profile uid and custom as alternatives even though neither appears in a required array. Send one, not both.
The posts schema describes page defaulting to 1 and feature to 0; the helper sends them explicitly. since_id describes a next-page identifier, so it is omitted here. No subsequent page, detail, comment or model call is made. The ordinary timeline can contain pinned items and reposts: do not turn its first item into a claim about the latest original post.
Connect an existing project or agent
If you already have a key, store it locally as SANDBASE_API_KEY and install requests in your project’s Python environment. Keep the key out of article examples, chat messages, logs and source control. Run the block below once with your chosen identifier.
If an agent is already connected to SandBase, ask it to inspect the selected endpoint and reuse that connection. It should make only the chosen request, preserve the business payload, and report an error rather than manufacture an empty account. It does not need to create another project or discover every endpoint.
For a new project, give your agent the setup skill and the Markdown quickstart, then state your task: “Read this known UID’s profile once, keep missing fields unknown, and stop after showing the result.” The human quickstart covers the account and key setup. Creating a key is not proof that an account lookup or free allowance will succeed.
One checked Python request
The helper below is deliberately bounded. Its numeric-string and custom-name checks are local input guards, not a guarantee that the account exists or a complete specification of Weibo username rules. A nonempty profile object is also a local completeness policy; optional fields remain optional.
import os
import re
import requests
def first_request(task, *, uid=None, custom=None):
if task not in ("profile", "posts"):
raise ValueError("Choose profile or posts")
if task == "profile":
if (uid is None) == (custom is None):
raise ValueError("Provide exactly one of uid or custom")
elif uid is None or custom is not None:
raise ValueError("Posts require uid only")
if uid is not None:
if not isinstance(uid, str) or not re.fullmatch(r"[0-9]+", uid):
raise ValueError("uid must be a numeric ID string")
params = {"uid": uid}
else:
if not isinstance(custom, str) or not custom.strip():
raise ValueError("custom must be a nonempty username")
value = custom.strip()
if "://" in value or "/" in value or any(c.isspace() for c in value):
raise ValueError("Provide the custom username, not a URL")
params = {"custom": value}
endpoint = "user-info" if task == "profile" else "user-posts"
if task == "posts":
params.update(page=1, feature=0)
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(
f"https://api.sandbase.ai/v1/api/weibo/web-v2/{endpoint}",
headers={"Authorization": f"Bearer {key}"},
json=params, timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"HTTP {response.status_code}; no retry performed")
body = response.json()
except ValueError:
raise RuntimeError("Response was not valid JSON") from None
except requests.RequestException:
raise RuntimeError("Network request failed; no retry performed") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("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("Missing business payload object")
if task == "profile":
if not isinstance(payload.get("user"), dict) or not payload["user"]:
raise RuntimeError("Missing profile user object")
else:
if type(payload.get("ok")) is not int or payload["ok"] != 1:
raise RuntimeError("Posts business request did not succeed")
data = payload.get("data")
if not isinstance(data, dict) or not isinstance(data.get("list"), list):
raise RuntimeError("Missing posts data.list array")
if any(not isinstance(item, dict) for item in data["list"]):
raise RuntimeError("Malformed post item")
return payload
if __name__ == "__main__":
result = first_request("profile", uid="1222135407")
print(result["user"].get("screen_name"))The default run only reads the profile. To read posts instead, replace the final two lines with result = first_request("posts", uid="1222135407") and print(len(result["data"]["list"])). For a custom-name lookup, replace the call with first_request("profile", custom="shuqi"). These are alternatives, not three steps to run in sequence.
The UID in the default example comes from the old article’s public-account experiment. The custom name comes from the current profile schema. Neither call was newly executed for this repair. In particular, the public profile README’s historical example sent both uid and custom; it is response-shape evidence, not proof that this newly constructed one-identifier request just ran.
Check success at both layers
An HTTP response is only the first check. Redirects, authentication/permission errors, quota/payment errors and server errors stop the example; it does not automatically resend a potentially chargeable operation. Timeouts and invalid JSON also stop with a short diagnostic. Inspect the failure before deciding whether another request is warranted.
A completed SandBase envelope must contain an object at outputs[0].data. The old top-level output fallback is not accepted. For a profile, the reference shows a user object; there is no invented ok: 1 requirement for that endpoint. For posts, the successful public reference shows integer ok: 1, a data object and a list of objects. Python True is deliberately rejected as a substitute for integer 1. An empty valid list is a valid empty page, while a missing list is an error.
There is a useful failure trap in the current saved posts example: its input uses uid: "example", and its response contains an outer code: 200 around a failed inner result with ok: 0. Do not copy that invalid identifier, mistake the saved example for success, or use code: 200 as a business-success test. The new request follows the numeric UID contract, and the helper rejects that failure shape.
Interpret the fields without inventing metrics
Use the response as a record of what was returned, not a promise that every reference field is always present. Missing followers_count is unknown, not zero; an explicit numeric zero remains zero. A false verification flag is different from an omitted flag. Display-name agreement and a verification label can help a human review identity, but neither selects the intended account automatically.
The public profile reference includes avatar URLs. Storing a URL does not verify that the image is still fetchable; this helper does not download media. Some reference strings are trimmed and are unsuitable as download targets. Likewise, a profile’s total engagement fields may be formatted strings. Do not silently coerce missing or unreadable values into counts for rankings.
For posts, retain returned fields and provenance before mapping a research table. One page may contain reposts, pinned content or truncated text. Like and comment counts measure the returned record, not reach, purchases or campaign impact. A missing original-post marker does not prove the item is organic. This request intentionally stops before full-text fetching, cross-account comparisons or sentiment analysis.
Price and request budget
The 2026-11-08 free inspections list a base price of $0.001 for each selected endpoint. Both qualify for an organization’s shared pool of 100 eligible API calls per day, resetting at 00:00 UTC. That is eligibility, not a check of your remaining allowance or a promise that this request will be free. This repair did not inspect the account balance or measure an actual charge.
Choosing the profile or the posts example makes one request. Deliberately running both would be two requests, with a $0.002 base-price estimate before quota treatment; it is not what the default code does. Additional pages, retries and detail reads need their own budget. The historical seven-call experiment below is not the current onboarding cost.
Historical catalog screenshot from the earlier article: its 52-endpoint count and Free Week label describe that capture, not current inventory or today’s remaining free allowance. Current selected prices were checked separately; use the POST Model API paths above.
Historical experiment: 2026-10-01, not a current pipeline
The retained cover illustrates the older search, ranking and comment-research idea; it is not a tested current pipeline or a result produced by the single-request helper.
The original search for Chinese National Geography returned 20 candidates (run 4a509105-eb13-4513-bc6b-9e515167d4c7). Related shop and media accounts appeared alongside the main account. The old helper preferred an exact nickname and otherwise selected the first result; that is not a reliable identity rule, so it is not retained in the current executable path.
The search result’s fans: 1167 contrasted with 11,677,520 profile followers ("1167.8万"). Another historical search showed fans: 1 for a roughly 158-million account ("1.58亿"). These observations suggested lost display units, not a general conversion formula. The profile run 59d3b350-2227-49e1-bb25-1790a06950cb returned this original trimmed JSON:
{
"user": {
"idstr": "1222135407",
"screen_name": "中国国家地理",
"followers_count": 11677520,
"followers_count_str": "1167.8万",
"friends_count": 373,
"statuses_count": 28394,
"verified": true,
"verified_reason": "《中国国家地理》官方微博",
"location": "北京",
"status_total_counter": {
"repost_cnt": "3,130,409",
"comment_cnt": "1,820,565",
"like_cnt": "7,438,106",
"total_cnt_format": "1238.9万"
}
}
}Those comma-formatted totals are historical values, not fresh measurements. The old lighter user-basic-info result lacked a numeric follower count. That observation does not guarantee today’s coverage for either endpoint.
The original-posts experiment used UID 1222135407: page 1 returned 47 posts (run cc08c1c1-9d06-4453-b0b6-35d44d04f1bb), and page 2 returned 50 nonoverlapping posts (run 2b5b4795-95ec-4180-96bc-ee397f16ed4a), covering about four weeks. No since_id or has_more appeared in those recorded responses. Changing data.total values, 27,299 and 27,807, did not match the profile’s statuses_count.
That success does not settle the current original-posts contract. Its current schema says the initial since_id must come from user-posts, while README Notes discusses obtaining it for subsequent pages and its cURL omits it. This conflict is unresolved. The current example uses ordinary user-posts instead; it neither invents a starting token nor silently runs another request. An older ordinary-timeline observation (run 16f18948-183c-446d-bbb3-d74731720f4e) did contain since_id, but it is not a new continuation test.
Historical original-posts parameter reference. Its since_id ambiguity remains unresolved for current execution; successful 2026-10-01 page numbers are not a new pagination guarantee.
Of the historical 97 original posts, one co-branded travel campaign had 6,254 reposts, 692 comments and 6,879 likes; the next repost count was 384. Only the campaign carried cooperate_info. The old code called the remaining ranking “organic,” but absence of that field does not establish absence of sponsorship. isAd appeared on 37 posts, including routine greetings, so it was not a dependable sponsorship classifier in that sample.
There were 67 long-text flags. The campaign’s feed preview had 147 characters; the detail run fff2fd24-3225-4ba1-921c-71f54cd4fb72 returned 238 characters under longText.content and roughly 5.94 million reads. That is a dated observation, not an endpoint or field revalidation in this repair. A historical TLS reset succeeded after a retry; this is not a reason to embed automatic retries in a new paid workflow.
Historical post-detail reference showing id and the long-text option. This repair does not call or revalidate post-detail.
The historical comment runs f62a40cf-d18e-4f6f-b90b-c1c2b30b0f71 and 5664ad51-897d-4e17-8ef4-052a8f70e2d8 returned 20 different comments each, using the returned numeric max_id as a string for the second request. They reported total_number: 692; a different earlier attempt added no new second-page comments. “All comments loaded” text appeared despite further results. These observations justify caution, not a new retry or completeness rule. The most-liked sampled comment had 17 likes; the old workflow dropped commenter identity from its output.
Historical post-comments reference with count, id and max_id. Comment pagination and its current availability were not retested.
The old assembled workflow intended seven endpoint calls: search, profile, two original-post pages, detail and two comment pages, before any retry. All eight original Python blocks per locale are preserved in the dated code archive, with hashes. It contains legacy envelope handling, retries, automatic account choice and zero defaults; it is an audit artifact, not current setup code.
FAQ
Do I need a Weibo login? These public read endpoints use a SandBase key. They do not authorize posting or access to private/follower-only data. Use the appropriate official account-authorized route for account actions.
Does this request return only original posts?
No. user-posts is the ordinary timeline and may contain reposts. The original-only experiment is retained as dated history because its current initial cursor guidance is inconsistent.
Can I page until everything is collected? Not with this example. It stops after page 1. Neither a single page nor the historical two-page experiment proves full history, reliable ordering or a working next-page recipe today.
Can I hand this to an agent? Yes: provide the setup skill, a known identifier and one task. Ask for the validated payload and unknown fields, with no automatic follow-up calls. Review the result before expanding the scope.
Wrap up
Start with the account information you actually have, choose one request, and validate both the SandBase envelope and the endpoint-specific business structure. Keep historical experiments useful by keeping their dates and limits visible. Open user info or user posts, then use the checked example above for the selected first task.
For a 2026 pricing comparison of the live SandBase Weibo hub, see Best Weibo API in 2026: Pricing Compared.
Found this useful? Share it