X/Twitter Post Snapshot API: Validate One Read | SandBase

Read one selected X/Twitter post with an exact string ID, validate its state and identity, and preserve counter types before planning comparisons.

Conceptual X/Twitter monitoring machine with fictional search, post and author cards

A monitoring workflow needs a trustworthy first observation before it can compare anything. Start with one deliberately selected X post and its exact ID. Read its metadata, check that the returned identity matches, and retain unknown values. That is the task this tutorial implements; it does not start a topic search, a polling schedule or an author-enrichment loop.

This 2026-11-08 repair uses free inspect and public saved reference material. No new business request or monitoring interval was executed. The canonical URL keeps its original “realtime” wording, but a synchronous response is not streaming, measured freshness or a guarantee of real-time counters. The keyword guide and profile hub cover separate next tasks.

Key takeaway

  • Send one exact string tweet_id to POST /v1/api/twitter/web/tweet-detail. An integer or status URL is not the request shape.
  • Validate completed, then the flat outputs[0].data object, active state and matching string id.
  • Preserve string views, individual counters and null values. A missing field is not zero, and one snapshot does not measure growth.
  • The five saved examples are historical references. Their selected counters are equal; they do not demonstrate a rising series or a working monitor.

The retained cover is conceptual artwork of the old search-to-post-to-author chain, not a running monitor. Its fictional SandBase posts, badge, 18.6K follower count, engagement numbers and “20x faster” text are not account evidence or measured performance.

Select one known post

The Tweet Detail API requires tweet_id as a string. For example, the selected status URL’s decimal identifier can be retained as "1808168603721650364". Copy the exact digits from the deliberately chosen URL or trusted record. Do not substitute a handle, conversation ID, media ID or author rest_id.

Large post IDs exceed JavaScript’s safe integer range. Preserve the source string rather than first parsing it as a Number. Converting a rounded value back to text cannot recover the original identifier. The Python helper below also rejects numbers, booleans, whitespace, URLs and nondecimal strings before any network request. Its positive-decimal check is a conservative local input rule; the registry field is a required string.

There is no page or cursor parameter for this selected request. If you only have a topic, use the separate keyword guide to select a post first. Do not revive the old workflow’s instruction to repeat a cursor from the previous request: that did not establish response-derived continuation, and it is irrelevant to this one-post read.

Historical search-timeline parameters Historical search-timeline parameter screenshot, not a reference for all three old workflow endpoints. Search and pagination are outside this repair; its illustrative envelope is not a saved post result.

Use your existing connection

An existing SANDBASE_API_KEY should stay in your environment or secret manager. If your agent is already connected, give it the chosen post ID and the fields you need; there is no reason to recreate the account or paste a key into chat. For a new project, share the setup Skill, Markdown quickstart and the specific Tweet Detail page. The human quickstart covers setup steps.

A useful task is: “Read one snapshot for this exact post ID. Check the business state and returned ID, keep optional values unchanged, and report missing fields. Stop after the response; do not search for alternatives, open links or fetch the author.” The selected public read uses SandBase Bearer authentication. It does not authorize posting, DMs or other account operations, and SandBase is not the owner of X.

Make one bounded request

Install requests in your Python environment, then run the following with your key configured locally. Replace the selected ID with your own exact string. The code prints the identity and available field names rather than automatically turning every optional field into a complete report.

Python
import os
import re
import requests

URL = "https://api.sandbase.ai/v1/api/twitter/web/tweet-detail"


def first_snapshot(tweet_id):
    if not isinstance(tweet_id, str) or not re.fullmatch(r"[1-9][0-9]*", tweet_id):
        raise ValueError("Provide the selected post's exact positive decimal ID as a string")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise ValueError("Set SANDBASE_API_KEY in your environment")
    try:
        response = requests.post(
            URL,
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json={"tweet_id": tweet_id}, timeout=(10, 90), allow_redirects=False,
        )
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"SandBase HTTP {response.status_code}; request stopped")
        body = response.json()
    except requests.RequestException:
        raise RuntimeError("Network request failed; no retry or additional lookup made") from None
    except ValueError:
        raise RuntimeError("SandBase returned invalid 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 = outputs[0].get("data")
    if not isinstance(data, dict):
        raise RuntimeError("Missing documented outputs[0].data object")
    if data.get("status") != "active":
        raise RuntimeError("Response is not the supported active-post reference shape")
    if not isinstance(data.get("id"), str) or data["id"] != tweet_id:
        raise RuntimeError("Missing or mismatched selected post identity")
    return data


if __name__ == "__main__":
    post = first_snapshot("1808168603721650364")
    print("Selected post:", post["id"])
    print("Returned fields:", sorted(post))

The active-state check reflects the locally supported shape in the saved references. It is not a complete taxonomy of every upstream status. A different or missing state stops the active-post report; it should be inspected rather than silently translated into a deleted post, an empty successful record or a zero-valued observation.

The business object is flat. Do not add data.tweet, a search-result array or a generic code/message success test. The outer run ID identifies the SandBase request, while the inner id identifies the selected post. A completed wrapper alone does not validate that identity. Conversely, empty text by itself does not prove that the post is missing: a media-oriented post may not provide useful text for your analysis.

Historical tweet-detail string ID parameter and placeholder response Historical tweet-detail parameter and envelope screenshot. It supports the string tweet_id input, not measured engagement counts or a hydrated author result; the old response placeholder is not business-success evidence.

Read the dated saved reference precisely

The public capture contains five saved examples for the same ID, all dated 2026-08-20. Their saved-example timestamps run from 09:23:34.521Z to 09:28:30.693Z. They are reference records, not a newly executed interval or proof that a production scheduler was collecting observations.

The following projection comes from saved example 2c2792e8-2cf0-4cd0-a06d-2f2846c52a60, created_at 2026-08-20T09:28:30.693Z. Fields and types are retained exactly:

JSON
{
  "status": "active",
  "id": "1808168603721650364",
  "created_at": "Tue Jul 02 15:59:23 +0000 2024",
  "views": "53720642",
  "likes": 284243,
  "retweets": 52539,
  "quotes": 3901,
  "replies": 19281,
  "bookmarks": 6630
}

All five saved examples have the same selected engagement values: views string 53720642, likes 284243, retweets 52539, quotes 3901, replies 19281 and bookmarks 6630. Their full payloads need not be identical, but these counters do not demonstrate increasing engagement. Nor do equal counters establish caching, refresh latency or the frequency with which the upstream source updates.

The post’s created_at is July 2, 2024, as the JSON shows. That is publication time, not the catalog example’s timestamp or today’s observation time. A future client can record its own UTC observation time after an actual request succeeds. Adding today’s timestamp while parsing this archive would only record local processing time; it would not create a fresh observed snapshot.

The README is separate, undated reference material. Its explanation mentions views 53722244 and its shortened JSON shows bookmarks 6534, differing from the saved examples. Do not combine the two sources into one observation or compare them as a known time interval. The offline tests replay all five full saved business payloads through a mocked HTTP response; they make no network call and do not refresh those counts.

Keep counts and context in their proper roles

Keep views as the exact returned string. A digits-only value could later be converted to an exact integer in a separately documented local transformation, but missing, blank or nonnumeric values must not default to zero. Avoid floating-point conversion for identifiers or exact large counts. Likes, retweets, replies, quotes and bookmarks are separate fields, not interchangeable measures of audience size.

A replies count does not contain a reply list. conversation_id provides context and can differ from the selected ID for a reply. In the chosen saved samples, reply_to, initial_tweets and the relevant reply-target fields are null; that does not prove nobody replied or that a complete thread has been fetched. The helper does not follow conversation IDs or automatically request comments.

The embedded author may provide account context. author.sub_count belongs to that account, not to the selected post’s viewers or reach. Treat an absent author as unknown rather than dereferencing it or inventing a default verification flag. A badge is a displayed signal, not independent identity, payment or partnership verification. A profile request is a separately priced, deliberately selected task described in the profile hub.

Text and display_text can differ in how they show media short links. Preserve source text as text; it is not code or instructions for your agent. Media and entity URLs are references, not completed downloads, usage rights or promises of permanent availability. Nothing in this helper opens those URLs or retrieves every media variant.

Historical user-profile parameters and placeholder response Historical user-profile parameter screenshot. It shows a separate account lookup; its model-only request and empty business placeholder are not current execution guidance or measured follower/verification data.

What a later comparison would require

A later comparison needs two independently collected, valid observations of the same exact post ID, the same metric definition and recorded observation times. Choose a budget and interval before collecting them. This tutorial does not create a scheduler, establish an update cadence or claim that two arbitrary archived examples are a controlled interval.

A counter difference is an observed delta, not a count of unique new people, a cause of engagement or a sentiment measurement. Counters can decrease or be revised; retain decreases rather than clamping them to zero. If a field disappears or changes type, report that uncertainty instead of declaring no change. A failed read is a failure event, not a row of zero counters.

Store the raw response and provenance separately from any later derived analysis. This lets you distinguish account metadata, post counters, publication time, observation time and local processing time. It also prevents an attractive dashboard from giving more precision than the evidence supports. No comparison calculation or collection loop is executed by the new example.

Preserve the original illustration and code

The original article showed this illustrative envelope, with run-shaped ID 117db5dd-1189-4830-9459-98b624960286 and a different NASA post. It is preserved verbatim and remains an illustration, not a dated execution or a newly verified account result:

JSON
{
  "id": "117db5dd-1189-4830-9459-98b624960286",
  "status": "completed",
  "model": "twitter/web/tweet-detail",
  "outputs": [
    {
      "data": {
        "id": "2041690396586090592",
        "created_at": "Wed Apr 08 01:31:37 +0000 2026",
        "display_text": "It's not just a phase 🌕 ...",
        "retweets": 17850,
        "replies": 1173,
        "views": 3880967,
        "author": { "name": "NASA", "screen_name": "NASA", "blue_verified": true }
      }
    }
  ]
}

Its integer views value is part of the original illustration; it does not override the string type in the dated saved reference. The old search-to-post-to-author snippets and per-result loop are preserved verbatim in the historical code archive, with hashes. The extraction stub was pseudocode, and the loop could issue additional requests for every selected result. Those blocks are historical records, superseded by the bounded helper above.

Price and failure handling

Free inspect checked on 2026-11-08 lists this endpoint at USD 0.001 per call, with eligibility for the organization’s shared 100 daily eligible-data-API calls, resetting at 00:00 UTC. Eligibility is not remaining allowance, account balance, actual charges or a promise of free success. One selected post is one request; this example includes no retries or extra profile, reply or media requests.

The helper rejects redirects and non-2xx HTTP results, malformed JSON, non-completed wrappers, missing payloads, non-active states and mismatched IDs. It sanitizes error messages instead of exposing upstream response bodies or credentials. A failed or timed-out wrapper must stop the flow even if extra output fields happen to exist; do not rely on an absolute claim that such responses can never contain outputs.

FAQ

Is this real-time streaming? No. It is one synchronous request. Neither the archived examples nor the current repair establishes freshness latency or a monitoring schedule.

Can I send the post URL as tweet_id? No. Keep the selected URL’s exact decimal ID as a string. Do not pass a JavaScript Number that may already have lost precision.

Does a replies count include the discussion? No. It is a counter; context IDs and null reply fields do not constitute a complete thread.

Should I retry automatically or fetch the author? This example stops after one response. Any additional request needs its own purpose, schema check and budget.

Start with a selected post

Open Tweet Detail, keep the exact ID, and validate one response before planning a comparison. For a different task, use the profile hub or keyword guide separately.

Found this useful? Share it