Toutiao Author Research API Tutorial | SandBase
Read one known Toutiao article through app or web, validate its response, preserve optional author fields and HTML, and keep historical research separate.

An article link can lead to two different research questions: what account and engagement metadata is available for this item, or what article text and publication metadata can I read? Toutiao’s app and web article routes serve those related tasks with different input names. A useful first integration chooses one route and inspects its response before collecting more articles or comments.
This 2026-11-08 repair checks free inspect and current public references. It makes no paid business request. The original 2026-10-01 UTC author-research experiments, run IDs and trimmed JSON remain below, with their limits. For the broader catalog, see the Toutiao public data API hub.
Key takeaway
- For an app article record, send the known numeric article ID as
group_id.- For a web article record, send that article ID as
aweme_id; do not substitutegroup_idon the web route.- Both selected references use completed
outputs[0].data, thenmessage: "success"and an innerdataobject.- Missing author metadata is unknown, not proof of deletion. Web
contentis HTML; this example does not render it, download images or fetch comments.
Choose one article request
| Your immediate task | Exact endpoint | Request field |
|---|---|---|
| Inspect an article’s available account and engagement metadata | App article info | group_id string |
| Inspect its available text and publication metadata | Web article info | aweme_id string |
Use a known article’s long numeric ID, such as 7450114952884503059 from https://www.toutiao.com/article/7450114952884503059/. The app reference also describes /group/<id>/ links. The helper accepts the ID only; it does not fetch a shared link, follow redirects or parse arbitrary URLs. Although the web field is named aweme_id, this selected route is for the Toutiao article, not a request to a different platform.
Both schemas declare only their respective required string field. No offset, author ID, language option or search keyword is added. Article-to-author research does not require three automatic calls: an app read and a web read are alternatives here, and comments are outside the first-request scope.
Continue with your existing key or agent
With an existing key, store SANDBASE_API_KEY locally and install requests in your Python environment. Keep the key out of prompts, source files and logs. The example checks it before network access and uses only the selected route.
If your agent already has a SandBase connection, ask it to inspect that endpoint and reuse the connection. Give it the known article ID, the desired surface and a one-request boundary. For example: “Read the web article record once, preserve the HTML as data, and report which metadata is present; do not download images or fetch comments.” It need not recreate a project or enumerate all available APIs.
For a new project, hand the agent the setup skill, the Markdown quickstart and the task. The human quickstart covers account and key setup. A key being configured does not prove the target is available or the shared free allowance has remaining calls.
One bounded Python request
The input check requires an ASCII numeric string. That is a local guard against wrong identifier types and accidental URLs, not proof that the article exists. The main block prints available field names so an absent author or title is not silently replaced with a fabricated record.
import os
import re
import requests
def first_request(surface, article_id):
if surface not in ("app", "web"):
raise ValueError("Choose app or web")
if not isinstance(article_id, str) or not re.fullmatch(r"[0-9]+", article_id):
raise ValueError("article_id must be a numeric string, not a URL")
field = "group_id" if surface == "app" else "aweme_id"
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/toutiao/{surface}/article-info",
headers={"Authorization": f"Bearer {key}"},
json={field: article_id}, 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 payload.get("message") != "success":
raise RuntimeError("Article business request did not succeed")
if not isinstance(payload.get("data"), dict):
raise RuntimeError("Missing article data object")
return payload
if __name__ == "__main__":
result = first_request("app", "7450114952884503059")
print("Available article fields:", ", ".join(result["data"]))To choose the web route, replace the final call with result = first_request("web", "7450114952884503059"); keep the following field-list print. Do not append it as a second automatic request. The example ID comes from the public schemas and the old article; it was not executed again for this repair.
The helper checks HTTP success, stops on redirects, handles timeout/connection and JSON failures, and requires completed status. Missing or malformed outputs[0].data is an error, not {}. It does not accept the historical top-level output fallback. Inside the business payload, both current references show exact message: "success" and a data object, so those are checked separately. An errno: 0 from another endpoint is not a substitute for this contract.
No retries, comments, pages, author lookups, media downloads or model calls occur. Errors omit the key and raw response body. A structurally valid empty inner object remains visibly empty; it is not a complete author card. Review the returned fields before deciding whether the response answers your research question or whether another request is justified.
Read optional author fields without overclaiming
The app reference describes data.user_info, engagement counts, share information and other fields. Its short JSON example is deliberately trimmed. The absence of user_info in that excerpt cannot prove it is absent from a full response. The original article’s real sample did contain it; that does not make every author’s card complete today.
If your actual record omits user_info, keep the publisher information unknown. Do not label the article deleted merely because the author card is missing. The historical experiment separately observed an explicit delete: 1 record; that is a different observation from missing metadata. The helper returns such fields unchanged so the caller can distinguish a deletion indicator from unavailable optional information.
Missing counts stay unknown; an explicit numeric zero remains zero, and a false verification flag differs from an omitted flag. Follower counts are not article reach. A recorded read count is not a verified unique audience or a forecast of future performance. A verification description can help review identity but does not authorize automatic ranking or outreach.
The older article found a sparse user-profile result for a particular media account. It is retained as a dated comparison, not evidence that the user-info endpoint generally fails. Do not replace every profile query with article data on that basis. Choose the source that answers the specific question, and check what your response actually supplies.
Preserve IDs and inspect saved examples carefully
Keep article IDs as strings from input through storage. They exceed JavaScript’s exact integer range. The local saved-example display capture illustrates this risk: its numeric group_id appears as 7450114952884504000, while the request and a string gidStr preserve 7450114952884503059. That is a captured serialization/display discrepancy, not proof the live API changed the article ID. Casting an already rounded number to a string cannot recover the lost digits.
For identity comparisons, prefer the original request and a verified string identifier when present; do not introduce a strict comparison against a rounded display number. The Python helper sends the original string and does not convert business IDs through floating-point values.
Those saved captures also contain rendering references such as $1d in content/context positions. They are not article text and should not become parser fixtures or new business evidence. Saved-example timestamps and public trimmed references describe existing material, not a successful request made by this repair. This distinction matters when reviewing screenshots or building a test from a copied page.
Web content is HTML, not a ready-made summary
The current web reference shows content as HTML and describes title, publication metadata, source-account data and images. The old experiment found several fields in h5_extra; current reference descriptions also mention top-level fields. Do not turn one observed location into a claim that another location can never occur. Inspect available fields and preserve their provenance.
This example returns the HTML unchanged as data. It does not execute it, insert it into a page, visit embedded links or retrieve images. If your application needs plain text, use an HTML parser appropriate to that application and test headings, entities, paragraph boundaries and embedded elements. The old regular expression stripped tags and truncated at 2,000 characters; it was a research excerpt, not reliable full-text extraction or sanitization.
Likewise, a media URL in a record is not a verified download. Some public reference URLs are shortened. Do not copy truncated strings as live targets or let an agent follow every URL without a separate task. Counting available metadata is a safer first milestone than claiming an entire article archive from one response.
Price and request budget
The 2026-11-08 free inspections list $0.001 base price for each selected endpoint. Both are eligible for an organization’s shared 100 calls per UTC day across eligible APIs, resetting at 00:00 UTC. Eligibility is not remaining quota. This repair checked neither account balance nor actual charge, and it does not promise that your call will be free.
Choose app or web and the helper makes one request. Deliberately running both estimates $0.002 at base prices before quota treatment; that is a separate choice. Comments, extra pages and retries add requests. The old three-link research run below has a different call budget and must not be presented as the cost of this first step.
Historical catalog screenshot: its seven-endpoint count and Free Week label describe the earlier capture, not current inventory or remaining allowance. The selected prices were checked separately; use the current POST Model API routes above.
Historical author research: 2026-10-01 UTC
The retained cover illustrates the earlier article-to-author-to-comments idea. Its cards and diagrams are conceptual, not evidence that this repair ran that pipeline.
The earlier Shandian News article experiment used app article-info (run 7ce8965e-01c0-4577-8f27-195eacffe3d3). This original trimmed business payload remains unchanged:
{
"data": {
"group_id": 7450114952884503059,
"read_count": 95,
"digg_count": 2,
"comment_count": 1,
"repin_count": 1,
"user_info": {
"name": "闪电新闻",
"user_id": 51050126444,
"media_id": 51201073347,
"fans_count": 5582263,
"user_verified": true,
"user_auth_info": "{\"auth_info\":\"闪电新闻官方账号\",\"auth_type\":\"5\"}"
}
},
"message": "success"
}The Xinhuanet article run a4b82d62-f916-4e48-a6fc-5133965ebd5f had a similar card, roughly 29.4 million followers and 26,000 reads. These are historical observations, not current measurements. In those records, user_id was numeric and user_auth_info was a JSON string; any conversion needs type checks, and numeric precision must be preserved before string conversion.
The earlier user-info comparison returned an empty name and 49 followers where an article card showed roughly 5.58 million. It appeared to point to a linked short-video profile. The original author could not determine whether the route or those specific accounts explained the mismatch. That uncertainty remains; this repair does not generalize the sample into an endpoint failure rule.
A separate historical article returned delete: 1 without user_info. The old helper skipped both deletion and any missing author card, collapsing two different cases. The current first request does not hide those records. An absent author card alone is insufficient to establish deletion.
Historical app article-info reference showing required group_id. Its empty example was a documentation placeholder, not evidence that the endpoint returns no author fields.
For the web call, the initial attempt incorrectly sent group_id and received a 400 reporting missing aweme_id. The captured run 19d6214f-a69e-448f-bdff-b0f62ba2c88f used the correct field and returned HTML, media_user_id and h5_extra metadata including a publication time such as 2024-12-19 21:31. The media account ID matched the earlier card in that experiment; the current code does not automatically execute the second request to make that comparison.
Historical web article-info reference. The Toutiao article identifier goes in aweme_id on this route; the screenshot is not a newly executed request.
The older comments experiment observed a thread with 1,076 comments. Run c61a4cd6-8502-44dc-a344-61a88bbe5b8e returned 20 comments, has_more: true and offset: 20; run 0e4c824c-d42c-4d36-9758-fc296c089d61 returned offset 40. Text, likes, reply count and creation time were observed fields. The old output dropped commenter names/IDs. Those are dated pagination observations, not a newly verified comment contract, and no continuation is implemented here.
Historical comments reference with group_id and string offset. Comments and continuation were not revalidated for this repair.
The old assembled run processed three links: two usable article cards and one deleted record. With one comments page for each usable article, its intended path made seven calls: two app reads plus two web reads plus two comment reads, and the deleted article’s app read. The earlier “three calls per article” wording did not cover the skipped record; extra comment pages or retries would add calls.
All five original Python blocks per locale are preserved byte-for-byte in the historical code archive, with hashes. It retains the legacy fallback, broad missing-card skip, regex HTML extraction and automatic multi-article/comment workflow for audit only. The old TLS-retry observation is not an instruction to add automatic retries now.
FAQ
Does a missing author card mean the article is deleted? No. Preserve the absence as unknown and distinguish it from an explicit deletion indicator. A shortened README example cannot establish absence in a full result either.
Which ID name should I send?
For app article-info, use group_id; for web article-info, use aweme_id. The known Toutiao article ID remains a string in both requests.
Can I give this directly to an agent? Yes. Give it the setup skill, a known article ID and one chosen surface. Require the validated result, unknown-field reporting and no automatic follow-up calls.
Does the example collect all comments or full text? It makes one article request and preserves the returned data. Comments are separate, and the web HTML is not rendered, cleaned or summarized by this helper.
Wrap up
Start with one known article and the question you need answered. Choose app or web, use its exact input field, and validate the success message and inner object before interpreting optional metadata. Continue from app article info, web article info or the API hub when you have reviewed the first response.
Found this useful? Share it