Twitter Keyword Search API Tutorial | SandBase

Build a Twitter/X keyword-search workflow: search a timeline, page results, and profile the authors — one SandBase key, no Twitter login, no SDK.

Dark cinematic render of a Twitter keyword search resolving into a timeline and an author profile, feeding an agent core

Search public Twitter/X posts by keyword with SandBase, inspect the returned timeline, and continue through results when a cursor is available. This tutorial starts with a direct HTTP request, then keeps the existing Python workflow for optionally profiling authors behind relevant posts. You need a SandBase API key; no Twitter/X login or SDK is required for this public, read-only workflow.

Start with the search request and result checks below. Author enrichment is optional, not a prerequisite for keyword search. Use the endpoint reference for accepted inputs and the HTTP response envelope. Its examples describe payload fields, but your parser should still handle missing fields rather than assume every result is identical.

Key takeaway

  • Start with search-timeline to find posts; use user-profile only when author context helps.
  • Each call is POST /v1/api/twitter/web/<path> with only that endpoint’s params, one SANDBASE_API_KEY.
  • Chain by natural inputs: a keyword drives search; a tweet’s screen_name becomes the screen_name for the profile call.
  • For another page, pass the returned next_cursor as the request’s cursor. Public, read-only data only.

Access and scope

This tutorial authenticates to SandBase with a Bearer API key and reads public search results. It does not sign in as an X account, post content, send DMs, or retrieve private messages. Account-authorized actions require a separate integration; they are not demonstrated here.

The workflow at a glance

  1. Search the timeline with twitter/web/search-timeline using a keyword.
  2. Profile the authors with twitter/web/user-profile using a tweet’s screen_name.

Each endpoint returns the shared envelope — an id, a status, the model, and the payload on a completed run. The reference documents the payload under outputs[0].data; read it defensively.

SandBase Twitter API page with the endpoints used in this workflow Historical catalog screenshot showing the search and profile endpoints. Its GET /apis/v1 labels describe the catalog surface; the examples below use the documented Model API POST /v1/api route.

Step 0: one helper for every call

Make one keyword-search request

Set SANDBASE_API_KEY in your local or server environment before running this command. It sends the required keyword and explicitly selects Top, the documented default. search_type also accepts Latest, Media, People, and Lists; inspect the chosen mode’s results before treating every entry as a post.

Shell
curl --fail-with-body --silent --show-error \
  'https://api.sandbase.ai/v1/api/twitter/web/search-timeline' \
  -H "Authorization: Bearer ${SANDBASE_API_KEY:?Set your SandBase API key}" \
  -H 'Content-Type: application/json' \
  --data '{"keyword":"AI agents","search_type":"Top"}' \
  -o x-search.json

Open x-search.json and inspect the HTTP response and run status before extracting results. Keep your key out of browser code, shared notebooks, and published request logs.

Use the same HTTP contract in Python

Install requests with python -m pip install requests, then run these Python blocks in the same script or notebook. Keep SANDBASE_API_KEY in the environment used by that process.

Python
import os
import requests

API = "https://api.sandbase.ai/v1/api"
HEADERS = {
    "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
    "Content-Type": "application/json",
}

def call(path: str, payload: dict) -> dict:
    resp = requests.post(f"{API}/{path}", headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    if body.get("status") != "completed":
        raise RuntimeError(f"{path} did not complete: status={body.get('status')!r}")
    # Direct HTTP calls in this tutorial use outputs[0].data.
    outputs = body.get("outputs")
    if not isinstance(outputs, list) or not outputs:
        raise RuntimeError("Completed HTTP response has no outputs array")
    first = outputs[0]
    data = first.get("data") if isinstance(first, dict) else None
    if not isinstance(data, dict):
        raise RuntimeError("Expected an object at outputs[0].data")
    return data

This helper is for direct HTTP calls, not a universal adapter for tool responses. The HTTP reference uses outputs[0].data; the November 4 tool record used output[0].data. Both outer fields were arrays in those records. Returning the entire output array is not the same as extracting its first item’s data.

Step 1: search the timeline

Python
data = call("twitter/web/search-timeline", {"keyword": "AI agents", "search_type": "Top"})
tweets = data.get("timeline", [])
next_cursor = data.get("next_cursor")
print(len(tweets), "tweets, more:", bool(next_cursor))

Read the timeline, not just the entry count

For direct HTTP results, inspect outputs[0].data.timeline. Treat tweet_id as a string identifier, screen_name as the author handle, and text as the returned post text. Keep creation time and engagement counts when present. Missing values should remain unknown, not become zero. conversation_id identifies the conversation; it is not a substitute for the individual post ID.

Save a supplied original post URL when available. Otherwise, when both the handle and post ID exist, construct https://x.com/<handle>/status/<id>. Preserve that source link alongside the excerpt. A nested quoted object describes a separate quoted post; do not silently merge its text or engagement into the outer result.

Recorded check, November 4, 2026: SandBase’s verification notes record one completed tool call for AI agents with Top: output[0].data.timeline contained 20 entries, all with tweet_id and screen_name. The direct HTTP curl call also completed; outputs[0].data.timeline contained 19 entries, all with a post ID and author handle. These are observations from those two calls, not guaranteed page sizes. They do not establish a success rate or explain the count difference. These are the November 4 records, not a new test at publication time.

SandBase API reference for the Twitter search-timeline endpoint Original search-timeline reference screenshot. Use the linked current reference for accepted parameters and response examples.

Page safely and deduplicate posts

To continue, send the returned next_cursor as the next request’s cursor, keeping the same keyword and search_type. The response field and request parameter have different names. Copy the cursor as an opaque string; do not edit it or reuse one from an unrelated query.

Set a page, time, or cost budget before looping. Stop when no usable next cursor is returned, the cursor repeats, the page is empty, or the budget is reached. Stop for inspection if a page adds no new post IDs. These are defensive client rules, not a claim that every search exhausts all matching posts.

Deduplicate by tweet_id across pages before counting posts or summarizing. Keep author deduplication in the existing profile workflow separately: several distinct posts can share one screen_name. The current Python examples fetch one search page and optionally enrich authors; they do not already implement an automatic pagination loop.

Step 2: profile the authors

Python
screen_names = {t.get("screen_name") for t in tweets if isinstance(t, dict) and t.get("screen_name")}

for name in list(screen_names)[:5]:
    profile = call("twitter/web/user-profile", {"screen_name": name})
    print(name, "-", profile.get("name"), "|", profile.get("friends"), "following")

The user-profile reference accepts a screen_name; use a returned screen_name when present. This optional step supplies account context, not independent verification of a post. Read profile values with .get() and leave missing values unknown. In particular, friends is the number of accounts followed, not the follower count. This refresh did not rerun author enrichment.

SandBase API reference for the Twitter user-profile endpoint Historical user-profile reference screenshot showing screen_name and rest_id. Follow the linked current reference for the current interface and schema.

Putting it together

Python
def research(keyword: str, max_authors: int = 5):
    data = call("twitter/web/search-timeline", {"keyword": keyword})
    tweets = data.get("timeline", [])
    seen, authors = set(), []
    for t in tweets:
        if len(authors) >= max_authors:
            break
        if not isinstance(t, dict):
            continue
        name = t.get("screen_name")
        if name and name not in seen:
            seen.add(name)
            profile = call("twitter/web/user-profile", {"screen_name": name})
            authors.append({"screen_name": name, "profile": profile})
    return {"tweets": tweets, "authors": authors}

Because both endpoints share the same envelope, the loop stays flat: one status check in call(...), one .get() pattern, and the screen_name flowing from a tweet into the profile call.

Common use cases

Brand and launch monitoring

Search a product name or hashtag with search-timeline, page with the cursor, and diff the tweet set across runs to inspect changes within the collected sample. Profile the loudest accounts to understand who is driving the conversation. Input: a keyword. Output: a timeline plus author profiles. Endpoints: search-timeline, user-profile.

Competitor and creator research

Search a competitor’s name or a niche topic, collect the recurring screen_names, and profile each with user-profile to build a shortlist using the fields actually returned. The example above prints the following count; it does not rank authors by followers. Input: a keyword. Output: an author shortlist with profile context. Endpoints: search-timeline, user-profile.

Topic and sentiment sampling

Pull a keyword’s timeline on a schedule to sample how a topic is discussed over time. When a returned post includes text and engagement counts, you can feed the sample to a model for downstream classification. Input: a keyword. Output: a timeline sample. Endpoint: search-timeline.

Practical notes

  • Page with a budget. Use the cursor and stopping rules above before adding a loop. Each search page and optional author lookup is another API call; consult current pricing and quota details on the endpoint pages.
  • Public, read-only data only. No posting, DMs, or private/account-only data. Authenticate with a SandBase API key.

Handle incomplete evidence and failed requests

A completed run is not proof of complete coverage or factual accuracy. Search results are a sample for the selected query and mode. Saved documentation examples may be trimmed, and returned text may need checking at the original source. Do not claim comprehensive history, complete threads, or verified sentiment from one page.

If the request fails, inspect the HTTP status and error body without exposing credentials. Check authentication and parameter names first. Use bounded backoff for transient failures, and stop rather than retry indefinitely. A parsing failure is not an empty search result; retain the response for diagnosis and report the limitation.

FAQ

Do I need a Twitter/X developer account or login? No. You authenticate to SandBase with your SANDBASE_API_KEY. These read endpoints need no X account or OAuth on your side.

How do I get from a tweet to its author? When a result has a screen_name, pass it as the screen_name to user-profile. Skip records without a handle.

How do I page through more tweets? Send the returned next_cursor as the next request’s cursor, keeping the same keyword and search_type. The response field and request parameter have different names; apply the stopping and deduplication rules above.

Can I read private tweets or DMs? No. The API returns public data only. Private and account-authorized content are out of scope.

Next: validate your search, then add author context

Begin with one keyword, inspect the response, and save deduplicated post links before expanding the search. Keep the existing author-profile step when account context helps; it enriches a keyword-search sample rather than verifying the posts’ claims.

Open the search-timeline API reference and playground for current parameters, response examples, pricing, and quota details.

For an optional next integration, explore SandBase Agents. Carry forward the query, source links, deduplication rules, and a bounded call budget. This tutorial does not demonstrate creating a hosted Agent or completing an Agent Session.

For the broader endpoint catalog, see the Twitter public data API hub.

Found this useful? Share it