scavio-x

Search X, read tweets and their replies and retweeters, pull user profiles and their tweets, replies, media, followers, and followings, and get trending topics as structured JSON. 11 endpoints.

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 https://scavio.dev (50 free credits to get started, no card required):

bash

export SCAVIO_API_KEY=sk_live_your_key

Every request is a POST with a JSON body and:

text

Authorization: Bearer $SCAVIO_API_KEY

Endpoints

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

Endpoint	Credits	Description
POST /api/v1/x/search	1	Search tweets and people
POST /api/v1/x/tweet	1	Full details for a single tweet
POST /api/v1/x/tweet/comments	1	Replies to a tweet (ranked or chronological)
POST /api/v1/x/tweet/retweeters	1	Users who retweeted a tweet
POST /api/v1/x/user	1	Profile details for a user
POST /api/v1/x/user/tweets	1	A user's tweets
POST /api/v1/x/user/replies	1	A user's tweets and replies
POST /api/v1/x/user/media	1	A user's media tweets
POST /api/v1/x/user/followers	1	A user's followers
POST /api/v1/x/user/followings	1	Accounts a user follows
POST /api/v1/x/trending	1	Trending topics for a country

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)

Parameter	Type	Default	Description
search	string	required	Search query (1-500 chars)
search_type	string	Top	Top, Latest, People, Photos, Videos
cursor	string	--	Pagination cursor from a prior next_cursor

Tweet (/tweet)

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

Tweet comments (/tweet/comments)

Parameter	Type	Default	Description
tweet_id	string	required	Tweet id
rank	string	top	top (ranked) or latest (chronological)
cursor	string	--	Pagination cursor

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

Parameter	Type	Default	Description
screen_name	string	required	Handle without @
cursor	string	--	Pagination cursor

Trending (/trending)

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

Examples

python

import os, requests

BASE = "https://api.scavio.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['SCAVIO_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).

json

{
  "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

bash

pip install langchain-scavio

python

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