X (Twitter) — Tool Reference
Search tweets, get user profiles, trends, threads, and more from X
Your AI assistant discovers and invokes these tools through the
MCP Server's meta tools —
it calls execute_tool with the tool name and arguments below.
# available_providers read
List available X/Twitter data providers and their supported capabilities for choosing the right source first.
Full description
List configured Twitter data providers and their capabilities. Call this first to see which providers are available.
No parameters.
Parameter schema (JSON)
{
"description": "Parameters for available_providers tool.",
"properties": {},
"title": "AvailableProvidersParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of available_providers tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"providers": {
"description": "List of configured providers with their capabilities",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Providers",
"type": "array"
},
"tool_provider_map": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Map of tool name to list of available providers",
"title": "Tool Provider Map",
"type": "object"
},
"suggested_defaults": {
"additionalProperties": {
"type": "string"
},
"description": "Suggested cheapest provider per tool",
"title": "Suggested Defaults",
"type": "object"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "AvailableProvidersResult",
"type": "object"
} # get_article read
Get an X Article (long-form post) by the tweet ID that links to it.
Full description
Get an X Article (long-form post) by the tweet ID that links to it. X Articles are long-form posts that can be published by X Premium+ subscribers. Only supported by the twitterapio provider — the official X API and SocialData do not have an articles endpoint. The tweet_id must be for a tweet that contains/links to an X Article. If the tweet is not an article, the API will return an error.
| Parameter | Type | Required | Description |
|---|---|---|---|
tweet_id | string | Yes | The tweet ID of the article post |
provider | string | No | Provider to use. Only 'twitterapio' supports articles — the official X API and SocialData do not have an articles endpoint. Default: "twitterapio" |
Parameter schema (JSON)
{
"description": "Parameters for get_article tool.",
"properties": {
"tweet_id": {
"description": "The tweet ID of the article post",
"title": "Tweet Id",
"type": "string"
},
"provider": {
"const": "twitterapio",
"default": "twitterapio",
"description": "Provider to use. Only 'twitterapio' supports articles — the official X API and SocialData do not have an articles endpoint.",
"title": "Provider",
"type": "string"
}
},
"required": [
"tweet_id"
],
"title": "GetArticleParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of get_article tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"article": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Raw article data (body, author, metadata)",
"title": "Article"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "ArticleResult",
"type": "object"
} # get_followers read
Get a user's followers.
Full description
Get a user's followers. Returns a list of users who follow the specified account. Results are NOT cached (follower lists change frequently). TwitterAPI.io accepts handles directly (no ID resolution needed). X API and SocialData require user ID resolution first. Results are paginated. Use next_cursor to fetch more.
| Parameter | Type | Required | Description |
|---|---|---|---|
handle | string | Yes | Twitter handle/username (with or without @) |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest, no ID resolution needed), 'socialdata', or 'x' (both need ID resolution) |
max_results | integer | No | Maximum number of followers to return Default: 20 |
cursor | string | null | No | Pagination cursor from a previous response |
Parameter schema (JSON)
{
"description": "Parameters for get_followers tool.",
"properties": {
"handle": {
"description": "Twitter handle/username (with or without @)",
"title": "Handle",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest, no ID resolution needed), 'socialdata', or 'x' (both need ID resolution)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"max_results": {
"default": 20,
"description": "Maximum number of followers to return",
"maximum": 100,
"minimum": 1,
"title": "Max Results",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous response",
"title": "Cursor"
}
},
"required": [
"handle",
"provider"
],
"title": "GetFollowersParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of tools returning multiple users (followers, following).",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"users": {
"description": "List of normalized users",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Users",
"type": "array"
},
"result_count": {
"default": 0,
"description": "Number of users returned",
"title": "Result Count",
"type": "integer"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor for next page",
"title": "Next Cursor"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "UserListResult",
"type": "object"
} # get_following read
Get users that a user is following.
Full description
Get users that a user is following. Returns a list of users the specified account follows. Results are NOT cached (following lists change frequently). TwitterAPI.io accepts handles directly (no ID resolution needed). X API and SocialData require user ID resolution first. Results are paginated. Use next_cursor to fetch more.
| Parameter | Type | Required | Description |
|---|---|---|---|
handle | string | Yes | Twitter handle/username (with or without @) |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest, no ID resolution needed), 'socialdata', or 'x' (both need ID resolution) |
max_results | integer | No | Maximum number of followed users to return Default: 20 |
cursor | string | null | No | Pagination cursor from a previous response |
Parameter schema (JSON)
{
"description": "Parameters for get_following tool.",
"properties": {
"handle": {
"description": "Twitter handle/username (with or without @)",
"title": "Handle",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest, no ID resolution needed), 'socialdata', or 'x' (both need ID resolution)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"max_results": {
"default": 20,
"description": "Maximum number of followed users to return",
"maximum": 100,
"minimum": 1,
"title": "Max Results",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous response",
"title": "Cursor"
}
},
"required": [
"handle",
"provider"
],
"title": "GetFollowingParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of tools returning multiple users (followers, following).",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"users": {
"description": "List of normalized users",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Users",
"type": "array"
},
"result_count": {
"default": 0,
"description": "Number of users returned",
"title": "Result Count",
"type": "integer"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor for next page",
"title": "Next Cursor"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "UserListResult",
"type": "object"
} # get_quotes read
Get quote tweets of a tweet.
Full description
Get quote tweets of a tweet. Returns tweets that quote the specified tweet. Quote tweets include the original tweet as a reference and add commentary. Results are paginated. Use next_cursor to fetch more.
| Parameter | Type | Required | Description |
|---|---|---|---|
tweet_id | string | Yes | The tweet ID to get quote tweets for |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API) |
max_results | integer | No | Maximum number of quote tweets to return Default: 20 |
cursor | string | null | No | Pagination cursor from a previous response |
bypass_cache | boolean | No | Skip reading from cache (still writes to cache) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_quotes tool.",
"properties": {
"tweet_id": {
"description": "The tweet ID to get quote tweets for",
"title": "Tweet Id",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"max_results": {
"default": 20,
"description": "Maximum number of quote tweets to return",
"maximum": 100,
"minimum": 1,
"title": "Max Results",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous response",
"title": "Cursor"
},
"bypass_cache": {
"default": false,
"description": "Skip reading from cache (still writes to cache)",
"title": "Bypass Cache",
"type": "boolean"
}
},
"required": [
"tweet_id",
"provider"
],
"title": "GetQuotesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of search/timeline tools returning multiple tweets.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"tweets": {
"description": "List of normalized tweets",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Tweets",
"type": "array"
},
"result_count": {
"default": 0,
"description": "Number of tweets returned",
"title": "Result Count",
"type": "integer"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor for next page",
"title": "Next Cursor"
},
"cached": {
"default": false,
"description": "Whether result came from cache",
"title": "Cached",
"type": "boolean"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "TweetListResult",
"type": "object"
} # get_replies read
Get replies to a tweet from all users, paginated with conversation context.
Full description
Get replies to a tweet from all users. Returns all replies in the conversation, not just the author's own thread. Use get_thread instead if you want only the author's reply chain. Results are paginated. Use next_cursor to fetch more.
| Parameter | Type | Required | Description |
|---|---|---|---|
tweet_id | string | Yes | The tweet ID to get replies for |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API) |
max_results | integer | No | Maximum number of replies to return Default: 20 |
cursor | string | null | No | Pagination cursor from a previous response |
bypass_cache | boolean | No | Skip reading from cache (still writes to cache) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_replies tool.",
"properties": {
"tweet_id": {
"description": "The tweet ID to get replies for",
"title": "Tweet Id",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"max_results": {
"default": 20,
"description": "Maximum number of replies to return",
"maximum": 100,
"minimum": 1,
"title": "Max Results",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous response",
"title": "Cursor"
},
"bypass_cache": {
"default": false,
"description": "Skip reading from cache (still writes to cache)",
"title": "Bypass Cache",
"type": "boolean"
}
},
"required": [
"tweet_id",
"provider"
],
"title": "GetRepliesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of search/timeline tools returning multiple tweets.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"tweets": {
"description": "List of normalized tweets",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Tweets",
"type": "array"
},
"result_count": {
"default": 0,
"description": "Number of tweets returned",
"title": "Result Count",
"type": "integer"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor for next page",
"title": "Next Cursor"
},
"cached": {
"default": false,
"description": "Whether result came from cache",
"title": "Cached",
"type": "boolean"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "TweetListResult",
"type": "object"
} # get_thread read
Get an author's self-reply thread from a tweet, returning only the author's own chained posts.
Full description
Get a tweet thread (the author's own reply chain). A thread is a series of tweets by the same author replying to their own previous tweets. This is different from get_replies which returns all replies from any user. For X API: requires author_id to build a search filter. If not provided, the tweet is fetched first to extract it automatically. For SocialData/TwitterAPI.io: uses dedicated thread endpoints.
| Parameter | Type | Required | Description |
|---|---|---|---|
tweet_id | string | Yes | The tweet ID to get the thread for (the first tweet in the thread) |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API) |
author_handle | string | null | No | Author's handle (needed for X API to filter thread from replies). If not provided, will attempt to resolve from the tweet. |
max_results | integer | No | Maximum number of tweets in the thread to return Default: 20 |
cursor | string | null | No | Pagination cursor from a previous response |
bypass_cache | boolean | No | Skip reading from cache (still writes to cache) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_thread tool.",
"properties": {
"tweet_id": {
"description": "The tweet ID to get the thread for (the first tweet in the thread)",
"title": "Tweet Id",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"author_handle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Author's handle (needed for X API to filter thread from replies). If not provided, will attempt to resolve from the tweet.",
"title": "Author Handle"
},
"max_results": {
"default": 20,
"description": "Maximum number of tweets in the thread to return",
"maximum": 100,
"minimum": 1,
"title": "Max Results",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous response",
"title": "Cursor"
},
"bypass_cache": {
"default": false,
"description": "Skip reading from cache (still writes to cache)",
"title": "Bypass Cache",
"type": "boolean"
}
},
"required": [
"tweet_id",
"provider"
],
"title": "GetThreadParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of search/timeline tools returning multiple tweets.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"tweets": {
"description": "List of normalized tweets",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Tweets",
"type": "array"
},
"result_count": {
"default": 0,
"description": "Number of tweets returned",
"title": "Result Count",
"type": "integer"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor for next page",
"title": "Next Cursor"
},
"cached": {
"default": false,
"description": "Whether result came from cache",
"title": "Cached",
"type": "boolean"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "TweetListResult",
"type": "object"
} # get_trends read
Get current trending topics for a location.
Full description
Get current trending topics for a location. Returns trending topics with tweet counts and search queries. Trends are cached for 15 minutes. Supported by X API and TwitterAPI.io only (NOT SocialData). TwitterAPI.io returns a minimum of 30 results -- the list will be sliced to the requested count. Common locations: worldwide, us, uk, japan, germany, new york, london, tokyo, san francisco. Also accepts numeric WOEIDs.
| Parameter | Type | Required | Description |
|---|---|---|---|
location | string | No | Location name (e.g., 'us', 'worldwide', 'new york') or numeric WOEID. Common locations: worldwide, us, uk, japan, germany, new york, london, tokyo. Default: "worldwide" |
provider | "x" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest) or 'x' (official API). SocialData does not support trends. |
count | integer | No | Maximum number of trends to return Default: 20 |
bypass_cache | boolean | No | Skip reading from cache (still writes to cache) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_trends tool.",
"properties": {
"location": {
"default": "worldwide",
"description": "Location name (e.g., 'us', 'worldwide', 'new york') or numeric WOEID. Common locations: worldwide, us, uk, japan, germany, new york, london, tokyo.",
"title": "Location",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest) or 'x' (official API). SocialData does not support trends.",
"enum": [
"x",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"count": {
"default": 20,
"description": "Maximum number of trends to return",
"maximum": 50,
"minimum": 1,
"title": "Count",
"type": "integer"
},
"bypass_cache": {
"default": false,
"description": "Skip reading from cache (still writes to cache)",
"title": "Bypass Cache",
"type": "boolean"
}
},
"required": [
"provider"
],
"title": "GetTrendsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of get_trends tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"trends": {
"description": "List of trending topics",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Trends",
"type": "array"
},
"location": {
"default": "",
"description": "Resolved location name",
"title": "Location",
"type": "string"
},
"woeid": {
"default": 0,
"description": "WOEID used for the query",
"title": "Woeid",
"type": "integer"
},
"result_count": {
"default": 0,
"description": "Number of trends returned",
"title": "Result Count",
"type": "integer"
},
"cached": {
"default": false,
"description": "Whether result came from cache",
"title": "Cached",
"type": "boolean"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "TrendsResult",
"type": "object"
} # get_tweet read
Get a single X/Twitter tweet by its ID.
Full description
Get a single tweet by its ID. Returns the tweet with full metadata including author info, engagement metrics (likes, retweets, replies, quotes, views), media, entities, and referenced tweets.
| Parameter | Type | Required | Description |
|---|---|---|---|
tweet_id | string | Yes | The tweet ID to retrieve |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API) |
bypass_cache | boolean | No | Skip reading from cache (still writes to cache) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_tweet tool.",
"properties": {
"tweet_id": {
"description": "The tweet ID to retrieve",
"title": "Tweet Id",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"bypass_cache": {
"default": false,
"description": "Skip reading from cache (still writes to cache)",
"title": "Bypass Cache",
"type": "boolean"
}
},
"required": [
"tweet_id",
"provider"
],
"title": "GetTweetParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of get_tweet tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"tweet": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Normalized tweet data",
"title": "Tweet"
},
"cached": {
"default": false,
"description": "Whether result came from cache",
"title": "Cached",
"type": "boolean"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "TweetResult",
"type": "object"
} # get_user read
Get an X/Twitter user's profile by their handle or username.
Full description
Get a Twitter user's profile by their handle/username. Returns the user's profile including bio, location, verification status, follower/following counts, tweet count, and profile images.
| Parameter | Type | Required | Description |
|---|---|---|---|
handle | string | Yes | Twitter handle/username (with or without @) |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API) |
bypass_cache | boolean | No | Skip reading from cache (still writes to cache) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_user tool.",
"properties": {
"handle": {
"description": "Twitter handle/username (with or without @)",
"title": "Handle",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"bypass_cache": {
"default": false,
"description": "Skip reading from cache (still writes to cache)",
"title": "Bypass Cache",
"type": "boolean"
}
},
"required": [
"handle",
"provider"
],
"title": "GetUserParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of get_user tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"user": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Normalized user data",
"title": "User"
},
"cached": {
"default": false,
"description": "Whether result came from cache",
"title": "Cached",
"type": "boolean"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "UserResult",
"type": "object"
} # get_user_mentions read
Get recent tweets mentioning a specific user, paginated with tweet metadata.
Full description
Get recent tweets mentioning a user. TwitterAPI.io accepts handles directly (no ID resolution needed). X API and SocialData require user ID resolution first. Results are paginated. Use next_cursor to fetch more.
| Parameter | Type | Required | Description |
|---|---|---|---|
handle | string | Yes | Twitter handle/username (with or without @) |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest, no ID resolution needed), 'socialdata', or 'x' (both need ID resolution) |
max_results | integer | No | Maximum number of tweets to return Default: 10 |
cursor | string | null | No | Pagination cursor from a previous response |
bypass_cache | boolean | No | Skip reading from cache (still writes to cache) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_user_mentions tool.",
"properties": {
"handle": {
"description": "Twitter handle/username (with or without @)",
"title": "Handle",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest, no ID resolution needed), 'socialdata', or 'x' (both need ID resolution)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"max_results": {
"default": 10,
"description": "Maximum number of tweets to return",
"maximum": 100,
"minimum": 1,
"title": "Max Results",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous response",
"title": "Cursor"
},
"bypass_cache": {
"default": false,
"description": "Skip reading from cache (still writes to cache)",
"title": "Bypass Cache",
"type": "boolean"
}
},
"required": [
"handle",
"provider"
],
"title": "GetUserMentionsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of search/timeline tools returning multiple tweets.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"tweets": {
"description": "List of normalized tweets",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Tweets",
"type": "array"
},
"result_count": {
"default": 0,
"description": "Number of tweets returned",
"title": "Result Count",
"type": "integer"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor for next page",
"title": "Next Cursor"
},
"cached": {
"default": false,
"description": "Whether result came from cache",
"title": "Cached",
"type": "boolean"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "TweetListResult",
"type": "object"
} # get_user_tweets read
Get recent tweets posted by a specific X/Twitter user.
Full description
Get recent tweets posted by a user. TwitterAPI.io accepts handles directly (no ID resolution needed). X API and SocialData require user ID resolution first. Results are paginated. Use next_cursor to fetch more.
| Parameter | Type | Required | Description |
|---|---|---|---|
handle | string | Yes | Twitter handle/username (with or without @) |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest, no ID resolution needed), 'socialdata', or 'x' (both need ID resolution) |
max_results | integer | No | Maximum number of tweets to return Default: 10 |
cursor | string | null | No | Pagination cursor from a previous response |
bypass_cache | boolean | No | Skip reading from cache (still writes to cache) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_user_tweets tool.",
"properties": {
"handle": {
"description": "Twitter handle/username (with or without @)",
"title": "Handle",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest, no ID resolution needed), 'socialdata', or 'x' (both need ID resolution)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"max_results": {
"default": 10,
"description": "Maximum number of tweets to return",
"maximum": 100,
"minimum": 1,
"title": "Max Results",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous response",
"title": "Cursor"
},
"bypass_cache": {
"default": false,
"description": "Skip reading from cache (still writes to cache)",
"title": "Bypass Cache",
"type": "boolean"
}
},
"required": [
"handle",
"provider"
],
"title": "GetUserTweetsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of search/timeline tools returning multiple tweets.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"tweets": {
"description": "List of normalized tweets",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Tweets",
"type": "array"
},
"result_count": {
"default": 0,
"description": "Number of tweets returned",
"title": "Result Count",
"type": "integer"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor for next page",
"title": "Next Cursor"
},
"cached": {
"default": false,
"description": "Whether result came from cache",
"title": "Cached",
"type": "boolean"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "TweetListResult",
"type": "object"
} # search_tweets read
Search X/Twitter for tweets matching a query, optionally filtered by user, language, or time.
Full description
Search for tweets matching a query. Supports Twitter search operators: - Keywords: python programming - From user: from:username - Hashtags: #python - Language: lang:en - Mentions: @username - Exclude: -keyword - Exact phrase: "exact phrase" Results are paginated. Use the next_cursor value to fetch additional pages.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query string. Supports Twitter search operators (e.g., 'from:user', '#hashtag', 'lang:en') |
provider | "x" | "socialdata" | "twitterapio" | Yes | Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API) |
max_results | integer | No | Maximum number of tweets to return Default: 10 |
sort | "top" | "recent" | No | Sort order: 'top' (engagement-ranked, default) or 'recent' (chronological). Note: 'top' is not supported by the socialdata provider — use 'recent' or choose another provider. With provider 'x', sort='top' disables pagination (X API limitation). Default: "top" |
cursor | string | null | No | Pagination cursor from a previous response |
bypass_cache | boolean | No | Skip reading from cache (still writes to cache) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for search_tweets tool.",
"properties": {
"query": {
"description": "Search query string. Supports Twitter search operators (e.g., 'from:user', '#hashtag', 'lang:en')",
"title": "Query",
"type": "string"
},
"provider": {
"description": "Provider to use: 'twitterapio' (cheapest), 'socialdata', or 'x' (official API)",
"enum": [
"x",
"socialdata",
"twitterapio"
],
"title": "Provider",
"type": "string"
},
"max_results": {
"default": 10,
"description": "Maximum number of tweets to return",
"maximum": 100,
"minimum": 1,
"title": "Max Results",
"type": "integer"
},
"sort": {
"default": "top",
"description": "Sort order: 'top' (engagement-ranked, default) or 'recent' (chronological). Note: 'top' is not supported by the socialdata provider — use 'recent' or choose another provider. With provider 'x', sort='top' disables pagination (X API limitation).",
"enum": [
"top",
"recent"
],
"title": "Sort",
"type": "string"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous response",
"title": "Cursor"
},
"bypass_cache": {
"default": false,
"description": "Skip reading from cache (still writes to cache)",
"title": "Bypass Cache",
"type": "boolean"
}
},
"required": [
"query",
"provider"
],
"title": "SearchTweetsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of search/timeline tools returning multiple tweets.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"tweets": {
"description": "List of normalized tweets",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Tweets",
"type": "array"
},
"result_count": {
"default": 0,
"description": "Number of tweets returned",
"title": "Result Count",
"type": "integer"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor for next page",
"title": "Next Cursor"
},
"cached": {
"default": false,
"description": "Whether result came from cache",
"title": "Cached",
"type": "boolean"
},
"provider": {
"default": "",
"description": "Provider that served the request",
"title": "Provider",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "TweetListResult",
"type": "object"
}