Weibo API v1

Available endpoints

Exact counts

A post's stats — reposts, comments, likes and reads — are exact figures, not the rounded ones on the page; roundedStats names any that came back rounded, and an empty list means every one is exact. A profile's stats.followers is exact too (23800264, not 2380万), with Weibo's rounded display beside it as followersText. In search results Weibo shows follower counts only rounded, as followersCountText; /user-profile gives the exact figure. A null field means Weibo did not publish that value, never zero.

Search reads through time

On tabs latest (the default), all, original and verified, /search-posts returns every matching post newest first, 50 to a page, and nextCursor keeps going back, for years if the term is old enough. since and until limit the period: a date is read as that day in China time, or pass an ISO date-time. top, hot and videos are Weibo's ranked picks and give one page per time range, so move the range to read other periods.

These are the posts Weibo's public search shows, which can leave out posts Weibo filters from search. Treat a search as what search shows for the term, not as a count of every post ever made about it. Search has no region filter.

Media: photos and video

Weibo's own media links open only from Weibo's pages, so every asset in media carries a downloadUrl pointing at GET /media, which opens anywhere and delivers the photo or video with Range support, so players can seek. A link that has expired is a 404: read the post again for a fresh one. Each request to /media costs 1 credit, and each range request counts as one.

Paging and billing

limit caps the items returned, and -1 means the maximum the route allows (up to 1000 search posts and 1000 comments in one request). When more exist, hasMore is true and nextCursor carries an opaque token to pass back unchanged as cursor, with the same request. A cursor is bound to the request that issued it — the same post, comment, account, sort, tab, since and until — and anything else is a 400 naming cursor. On /user-posts a cursor only continues a mediaOnly listing: sending one without mediaOnly: true is a 400.

Billing follows results returned, and every response states it as pagesFetched: 1 credit for /post-detail, /user-profile, /search-users and /trending; 1 per 20 comments or replies returned; 1 per 50 search posts returned, and 9 for tab: "combined"; 1 per 50 returned for /user-posts, or with mediaOnly 1 per 48. /resolve-url is free.

Read the notes array

Every response carries notes, and an empty result always comes with one explaining it. Every response also carries skippedRecords — records Weibo sent that could not be read, each with an id, a reason and the fields it did carry. It is normally empty: one unreadable record never costs the rest of the response. The ones you will see: a list that ends where Weibo stops showing more, a long post shortened in a list (post-detail has the full text), paid placements left out of the hot list, and a post with no public comments.

Requests are strict

An unrecognised body field is a 400 naming it, not a silent no-op, so a typo fails loudly instead of being answered with the wrong data. Enum values such as tab and sort are case-insensitive.

What this API does not return

• An account's posts beyond roughly its newest 2,000. /user-posts pages back that far with nextCursor. mediaOnly: true reaches further back, but lists only posts with photos or video. To read older posts on a subject, search for it with since and until.
• Every comment on a very large thread. A thread stops at a few hundred comments — about 300 most-liked, or about 740 newest first — however many Weibo counts, and notes says so.
• Reposts lists and follower lists. Not available. A post's repost count and a profile's follower count are.
• A region filter on search, and a guarantee that search is complete: it returns the posts Weibo's public search shows.
• Historical snapshots. Counts and the hot list are as at the time of the request; store what you get back if you want a time series.