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.

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-timelineto find posts; useuser-profileonly when author context helps.- Each call is
POST /v1/api/twitter/web/<path>with only that endpoint’s params, oneSANDBASE_API_KEY.- Chain by natural inputs: a
keyworddrives search; a tweet’sscreen_namebecomes thescreen_namefor the profile call.- For another page, pass the returned
next_cursoras the request’scursor. 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
- Search the timeline with
twitter/web/search-timelineusing akeyword. - Profile the authors with
twitter/web/user-profileusing a tweet’sscreen_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.
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.
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.jsonOpen 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.
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 dataThis 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
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.
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
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.
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
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