X/Twitter API for AI Agents: Search, Trends, Tweet Detail, and Profiles

The first useful test is not asking an LLM to summarize X. It is asking whether one search result still has a tweet ID, author, timestamp, and source URL after it leaves the API. If those fields disappear, the agent has a paragraph, not evidence.

X/Twitter is valuable for finding leads, but the feed is noisy and fast-moving. The design decision that matters is separating discovery, verification, and action. SandBase makes that separation concrete with small, inspectable Twitter routes rather than one opaque “social search” tool.

This guide shows a conservative pattern with SandBase’s Twitter API surface: search a keyword, read current trends, fetch a specific tweet, and enrich it with profile data. The examples use the unified POST /v1/run endpoint and keep the X layer separate from model reasoning.

Key takeaway

Search and trends are discovery signals; tweet detail and profile routes add context.

Preserve IDs, timestamps, authors, text, and canonical URLs before asking a model to summarize.

Treat Top results and engagement counts as metadata, not proof.

Keep posting behind a human approval boundary.

The short version

Use twitter/web/search-timeline to discover posts for a keyword.
Use twitter/web/trending to find country-specific trend candidates.
Use twitter/web/tweet-detail to inspect a post after discovery.
Use twitter/web/user-profile when author context changes the decision.
Pass only selected, structured evidence to an LLM; do not ask the model to treat a trending label as proof.
Keep posting actions out of an autonomous research agent. Reading and publishing have different risk boundaries.

What the API surface covers

SandBase’s public Twitter catalog currently exposes routes for search, trends, tweet detail, profiles, media, replies, followers, followings, comments, and retweet-user lists. The live model pages are the source of truth for parameters and response fields.

Figure 1. The catalog makes the permission surface visible: search, trends, tweet detail, profiles, and posting are separate models.

The four read operations below make a useful minimum toolset:

Job	SandBase model	Typical input
Search	`twitter/web/search-timeline`	`keyword`, optional `search_type` and `cursor`
Trends	`twitter/web/trending`	`country`
Tweet detail	`twitter/web/tweet-detail`	tweet URL or ID shown by the model page
Profile	`twitter/web/user-profile`	username or profile identifier shown by the model page

Pin the model slug you tested. A route name is an integration contract, not a promise that every provider field remains unchanged forever.

Call the API directly

Every operation uses the same endpoint and bearer authentication:

curl -X POST https://api.sandbase.ai/v1/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -d '{
    "model": "twitter/web/search-timeline",
    "keyword": "AI agent",
    "search_type": "Top"
  }'

The response contains a structured timeline. Preserve the tweet ID, author handle, creation time, engagement fields, and the original text. Do not copy the whole response into a prompt by default; select the fields your research task needs.

The search-timeline model page documents the required keyword input and the optional search_type and cursor fields.

Figure 2. The model page is the operational contract for a search call.

For trends, the catalog documents a country input. A trend is a discovery signal, not a claim that the topic is relevant to AI or that it is organically popular. Filter it through your own topic taxonomy before spending model tokens.

Figure 3. Trends are scoped by country in the current model contract.

A two-stage agent loop

The reliable pattern is a small deterministic collector followed by an LLM researcher:

import os
import requests

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

def run(model: str, **inputs) -> dict:
    response = requests.post(
        API,
        headers=HEADERS,
        json={"model": model, **inputs},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

timeline = run(
    "twitter/web/search-timeline",
    keyword="MCP agent",
    search_type="Top",
)

The collector should normalize each result into a small evidence object:

{
  "tweet_id": "...",
  "author": "@handle",
  "created_at": "...",
  "text": "...",
  "url": "https://x.com/handle/status/...",
  "source": "sandbase-twitter-search",
  "retrieved_at": "..."
}

Only then should an LLM answer questions such as “Which posts describe a new model release?” The LLM can classify, summarize, and propose follow-up sources; it should not invent a release date or turn an affiliate thread into product evidence.

Search, trends, and detail solve different problems

Search is best for a known vocabulary: a company name, model name, API feature, or protocol. Trends are best for broad discovery and local context. Tweet detail is best for verification after you already have an ID or URL. Profile data helps determine whether an account is an official publisher, a maintainer, a researcher, or a high-volume commentator.

Do not collapse these operations into one “social search” tool. Separate tools make the agent’s plan visible and let you apply different caching and approval rules.

Guardrails that matter

Treat engagement as metadata

Likes, reposts, views, and bookmarks describe activity returned by the API. They do not prove correctness, product availability, or user demand. Store them as fields and keep “evidence strength” as a separate value in your own pipeline.

Keep read and write permissions apart

The catalog also shows a user-post-tweet capability. A research agent should not have that tool. If a human-approved publishing workflow is ever added, isolate it behind an explicit approval step, a reviewable draft, and a separate credential boundary.

Cache with timestamps

Cache by (model, input, route_version) and store retrieved_at. X content changes quickly; a timestamp lets a reviewer distinguish a current observation from an old snapshot. Retry timeouts with bounded backoff, but do not retry malformed inputs or authorization failures indefinitely.

Cite the original post and the primary source

An X post can be the lead, not the final authority. For a model launch, follow the post to the vendor’s release note or documentation. For an API claim, verify the live SandBase model page and the provider’s documentation before publishing.

Where SandBase fits

SandBase is useful when the same research agent needs social discovery plus models, search, media, or other real-world APIs. The X collector remains a structured API call; the LLM remains a reasoning layer; the final output can be a brief, a ticket, or a Blog research note. This separation makes failures inspectable and keeps credentials on the server side.

Start with the Twitter search timeline API, then add trending and tweet detail only when the workflow needs them. For a broader social-data architecture, see Social Media Data APIs for AI Agents.

FAQ

Can an agent automatically post to X?

The catalog exposes a posting capability, but this guide intentionally excludes it. Publishing is an external side effect and needs an explicit human-approved workflow, not a default research tool.

No. Use it as a lead. Check relevance, duplication, primary sources, search intent, and whether SandBase has a truthful contribution before writing.

Should I send every tweet to the LLM?

No. Filter and normalize first. Passing only relevant fields lowers cost, reduces prompt injection exposure, and makes the evidence trail easier to review.