Scavio X

X via Scavio

Search X, read a single tweet with its replies and retweeters, pull a user's profile and their tweets, replies, media, followers, and followings, and get trending topics by country. All endpoints return structured JSON.

When to trigger

Use this skill when the user asks to:

• Search tweets or people on X for a topic or keyword
• Read a tweet's full details, its replies, or who retweeted it
• Look up a user's profile by handle
• Pull a user's tweets, replies, or media
• List a user's followers or the accounts they follow
• Get trending topics for a country
• Monitor brand, competitor, or campaign mentions
• Build RAG or sentiment pipelines that need social context

Setup

Get a free API key at scavio.dev (50 free credits to get started, no card required):

export SCAVIO_API_KEY=sk_live_your_key

Every request is a POST with a JSON body and:

Authorization: Bearer $SCAVIO_API_KEY

Endpoints

Base URL: https://api.scavio.dev. All paths are under /api/v1/x. Every endpoint costs 1 credit.

Workflow

1. Find tweets or people: call /x/search with search. Use search_type to switch category (Top, Latest, People, Photos, Videos). Read timeline[].tweet_id.
2. Read a tweet: call /x/tweet with tweet_id for full metrics.
3. Read the conversation: call /x/tweet/comments with tweet_id (set rank: latest for chronological), and /x/tweet/retweeters for who retweeted.
4. Look up a user: call /x/user with screen_name (a handle without @).
5. User activity: call /x/user/tweets, /x/user/replies, or /x/user/media with screen_name.
6. Social graph: call /x/user/followers and /x/user/followings.
7. Discovery: call /x/trending with a country name.

Paginated endpoints return next_cursor (and often prev_cursor); pass next_cursor back as cursor for the next page. Stop when it is null.

Parameters

Search (/search)

Tweet (/tweet)

tweet_id* — a tweet id, e.g. 1808168603721650364.

Tweet comments (/tweet/comments)

Tweet retweeters (/tweet/retweeters)

tweet_id* , cursor (optional).

User (/user)

screen_name* — an X handle without @, e.g. elonmusk.

User tweets / replies / media / followers / followings

Trending (/trending)

country (optional, default UnitedStates) — a country name.

Examples

import requests

BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Search — use "search", not "query"
results = requests.post(f"{BASE}/api/v1/x/search", headers=HEADERS,
    json={"search": "AI agents", "search_type": "Latest"}).json()

tweet_id = results["data"]["timeline"][0]["tweet_id"]

# 2. Full tweet + its replies
tweet = requests.post(f"{BASE}/api/v1/x/tweet", headers=HEADERS,
    json={"tweet_id": tweet_id}).json()

comments = requests.post(f"{BASE}/api/v1/x/tweet/comments", headers=HEADERS,
    json={"tweet_id": tweet_id, "rank": "latest"}).json()

# 3. A user's recent tweets
user_tweets = requests.post(f"{BASE}/api/v1/x/user/tweets", headers=HEADERS,
    json={"screen_name": "elonmusk"}).json()

# 4. Trending in a country
trending = requests.post(f"{BASE}/api/v1/x/trending", headers=HEADERS,
    json={"country": "UnitedStates"}).json()

Response shapes

Every response uses the envelope { data, response_time, credits_used, credits_remaining }. Key data fields per endpoint:

• search — timeline[] (type, tweet_id, screen_name, text, lang, created_at, favorites, retweets, replies, quotes, bookmarks, views, source), next_cursor, prev_cursor.
• tweet — tweet_id, text, display_text, created_at, lang, favorites, retweets, replies, quotes, bookmarks, views, source, reply_to.
• tweet/comments — timeline[] (tweet_id, screen_name, text, created_at, favorites, ...), next_cursor, prev_cursor.
• tweet/retweeters — retweeters[] (user_id, screen_name, name, description, followers_count, friends_count, statuses_count, media_count, profile_image), next_cursor.
• user — rest_id, screen_name, name, description, followers_count, friends_count, statuses_count, media_count, blue_verified, avatar, header_image, created_at, location, website.
• user/tweets — pinned (a tweet), timeline[] (tweet_id, text, created_at, favorites, retweets, replies, quotes, views, conversation_id), next_cursor.
• user/replies — timeline[] (same tweet item shape), user, next_cursor.
• user/media — timeline[] (same tweet item shape), user, next_cursor.
• user/followers — followers_count, followers[] (user_id, screen_name, name, description, followers_count, blue_verified, location), next_cursor.
• user/followings — following[] (same user item shape), next_cursor, more_users.
• trending — trends[] (name, description, context).

{
  "data": {
    "timeline": [
      {
        "type": "tweet",
        "tweet_id": "1808168603721650364",
        "screen_name": "OpenAIDevs",
        "text": "Shipping agent tooling this week.",
        "lang": "en",
        "created_at": "2026-06-30T18:04:11+0000",
        "favorites": 4821,
        "retweets": 902,
        "replies": 311,
        "quotes": 77,
        "views": 512340,
        "source": "Twitter Web App"
      }
    ],
    "next_cursor": "DAADDAABCgAB...",
    "prev_cursor": "DAABCgABCgAB..."
  },
  "credits_used": 1,
  "credits_remaining": 999
}

Guardrails

• The search field is search, not query — this differs from some other Scavio endpoints.
• screen_name is a handle without the leading @.
• Every X endpoint costs 1 credit. Inform the user before paginating through many pages.
• Never fabricate tweet ids, handles, metrics, or replies. Only return API data.
• Surface engagement metrics as-is; do not round or invent counts.

Failure handling

• 400 means an invalid or missing parameter (e.g. no tweet_id or screen_name) — fix and retry.
• 401 means the API key is invalid or missing. Check SCAVIO_API_KEY.
• 429 means rate or usage limit exceeded. Wait before retrying. See https://scavio.dev/docs/rate-limits.
• 502 / 503 mean upstream is temporarily unavailable. Wait a few seconds before retrying.
• If search returns no results, suggest different keywords or a different search_type.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.

LangChain

pip install langchain-scavio==4.0.2

from langchain_scavio import ScavioSearchTool
tool = ScavioSearchTool(engine="x")