{ "openapi": "3.0.3", "info": { "title": "Twitter API", "version": "1.0.0", "description": "Twitter API endpoints for user data and interactions." }, "servers": [ { "url": "https://api.aisa.one/apis/v1" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "UserFollowingsResponse": { "type": "object", "properties": { "followings": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "has_next_page": { "type": "boolean" }, "next_cursor": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "error" ] }, "msg": { "type": "string" }, "code": { "type": "integer" } } }, "UserMentionsResponse": { "type": "object", "properties": { "tweets": { "type": "array", "items": { "$ref": "#/components/schemas/Tweet" } }, "has_next_page": { "type": "boolean" }, "next_cursor": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "error" ] }, "msg": { "type": "string" }, "code": { "type": "integer" } } }, "FollowRelationshipResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "following": { "type": "boolean" }, "followed_by": { "type": "boolean" } } }, "status": { "type": "string", "enum": [ "success", "error" ] }, "message": { "type": "string" } } }, "SearchUserResponse": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "has_next_page": { "type": "boolean" }, "next_cursor": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "error" ] }, "msg": { "type": "string" } } }, "VerifiedFollowersResponse": { "type": "object", "properties": { "followers": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "status": { "type": "string", "enum": [ "success", "error" ] }, "msg": { "type": "string" }, "has_next_page": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "code": { "type": "integer" } } }, "User": { "type": "object", "properties": { "type": { "type": "string" }, "userName": { "type": "string" }, "url": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "isBlueVerified": { "type": "boolean" }, "verifiedType": { "type": "string" }, "profilePicture": { "type": "string" }, "coverPicture": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "string" }, "followers": { "type": "integer" }, "following": { "type": "integer" }, "canDm": { "type": "boolean" }, "createdAt": { "type": "string" }, "favouritesCount": { "type": "integer" }, "hasCustomTimelines": { "type": "boolean" }, "isTranslator": { "type": "boolean" }, "mediaCount": { "type": "integer" }, "statusesCount": { "type": "integer" }, "withheldInCountries": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "pinnedTweetIds": { "type": "array", "items": { "type": "string" } }, "isAutomated": { "type": "boolean" }, "automatedBy": { "type": "string" }, "unavailable": { "type": "boolean" }, "message": { "type": "string" }, "unavailableReason": { "type": "string" } } }, "Tweet": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "source": { "type": "string" }, "retweetCount": { "type": "integer" }, "replyCount": { "type": "integer" }, "likeCount": { "type": "integer" }, "quoteCount": { "type": "integer" }, "viewCount": { "type": "integer" }, "createdAt": { "type": "string" }, "lang": { "type": "string" }, "bookmarkCount": { "type": "integer" }, "isReply": { "type": "boolean" }, "inReplyToId": { "type": "string" }, "conversationId": { "type": "string" }, "displayTextRange": { "type": "array", "items": { "type": "integer" } }, "inReplyToUserId": { "type": "string" }, "inReplyToUsername": { "type": "string" }, "author": { "$ref": "#/components/schemas/User" }, "entities": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "object", "properties": { "indices": { "type": "array", "items": { "type": "integer" } }, "text": { "type": "string" } } } }, "urls": { "type": "array", "items": { "type": "object", "properties": { "display_url": { "type": "string" }, "expanded_url": { "type": "string" }, "indices": { "type": "array", "items": { "type": "integer" } }, "url": { "type": "string" } } } }, "user_mentions": { "type": "array", "items": { "type": "object", "properties": { "id_str": { "type": "string" }, "name": { "type": "string" }, "screen_name": { "type": "string" } } } } } } } } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/twitter/user/followings": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 2", "nominal_usd": 0.036, "observed_usd": { "min": 0.0006, "p50": 0.036, "p95": 0.036, "max": 0.036 }, "cost_drivers": [ { "param": "result count", "effect": "charge scales with number of tweets/users returned" } ], "cost_tier": "variable", "note": "nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower" }, "tags": [ "https://docs.twitterapi.io/api-reference/endpoint/get_user_followings" ], "summary": "Get User Followings", "operationId": "get_twitter_user_followings", "description": "List the accounts a given X user follows, identified by @handle. Returns 200 entries per page with `has_next_page` and `next_cursor`. Use this to infer a user's interests, information sources, or professional network — who someone follows is usually a stronger signal of intent than who follows them. For the opposite direction use `get_twitter_user_followers`. To test a single specific pair without paging through thousands of records, use `get_twitter_user_check_follow_relationship`.", "parameters": [ { "name": "userName", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Screen name of the user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor to paginate through the results. First page is empty." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 200, "minimum": 20, "maximum": 200 }, "description": "The number of followings to return per page." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFollowingsResponse" } } } } } } }, "/twitter/user/mentions": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 2", "nominal_usd": 0.0036, "observed_usd": { "min": 0.00015, "p50": 0.0021, "p95": 0.0036, "max": 0.006 }, "cost_drivers": [ { "param": "result count", "effect": "charge scales with number of tweets/users returned" } ], "cost_tier": "variable", "note": "nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower" }, "tags": [ "https://docs.twitterapi.io/api-reference/endpoint/get_user_mention" ], "summary": "Get User Mentions", "operationId": "get_twitter_user_mentions", "description": "Get tweets that mention a given @handle, 20 per page. This is the only user-scoped X endpoint that supports a time window: pass `sinceTime` and/or `untilTime` as Unix timestamps in seconds to bound the range. Use this for monitoring — brand mentions, inbound replies, reputation tracking, or 'what happened to this account in the last 24 hours'. Returns tweets with `has_next_page` and `next_cursor`. For the account's own posts rather than mentions of it, use `get_twitter_user_tweet_timeline`.", "parameters": [ { "name": "userName", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The user screen name to get mentions for." }, { "name": "sinceTime", "in": "query", "schema": { "type": "integer", "format": "int64" }, "description": "On or after a specified unix timestamp in seconds." }, { "name": "untilTime", "in": "query", "schema": { "type": "integer", "format": "int64" }, "description": "Before a specified unix timestamp in seconds." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor to paginate through the results. First page is empty." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMentionsResponse" } } } } } } }, "/twitter/user/check_follow_relationship": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 1", "nominal_usd": 0.0012, "observed_usd": { "min": 0.001, "p50": 0.001, "p95": 0.0012, "max": 0.0012 }, "cost_drivers": [ { "param": "result count", "effect": "charge scales with number of tweets/users returned" } ], "cost_tier": "variable", "note": "nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower" }, "tags": [ "https://docs.twitterapi.io/api-reference/endpoint/check_follow_relationship" ], "summary": "Check Follow Relationship", "operationId": "get_twitter_user_check_follow_relationship", "description": "Check whether one X user follows another, in both directions, by @handle. Use this for a single targeted lookup instead of paging through `get_twitter_user_followers` or `get_twitter_user_followings` — it answers 'does A follow B, and does B follow A' in one request. Returns the relationship flags under `data`.", "parameters": [ { "name": "source_user_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Screen name of the source user." }, { "name": "target_user_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Screen name of the target user." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowRelationshipResponse" } } } } } } }, "/twitter/user/search": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 2", "nominal_usd": 0.0012, "observed_usd": { "min": 0.00015, "p50": 0.0012, "p95": 0.0072, "max": 0.0072 }, "cost_drivers": [ { "param": "result count", "effect": "charge scales with number of tweets/users returned" } ], "cost_tier": "variable", "note": "nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower" }, "tags": [ "https://docs.twitterapi.io/api-reference/endpoint/search_user" ], "summary": "Search User by Keyword", "operationId": "get_twitter_user_search", "description": "Search X user accounts by keyword and get back matching profiles. Use this when you know roughly who you are looking for — a company name, a topic, a partial handle — but not the exact @handle. Cursor-paginated; returns full user objects under `users`. This searches accounts, not posts; to search tweet content use `get_twitter_tweet_advanced_search`.", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The keyword to search." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor to paginate through the results. First page is empty." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchUserResponse" } } } } } } }, "/twitter/user/verifiedFollowers": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 2", "nominal_usd": 0.00044, "observed_usd": { "min": 0.00044, "p50": 0.00044, "p95": 0.012, "max": 0.012 }, "cost_drivers": [ { "param": "result count", "effect": "charge scales with number of tweets/users returned" } ], "cost_tier": "variable", "note": "nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower" }, "tags": [ "https://docs.twitterapi.io/api-reference/endpoint/get_user_verified_followers" ], "summary": "Get User Verified Followers", "operationId": "get_twitter_user_verified_followers", "description": "List only the verified accounts following a given X user, in reverse chronological order. Use this to gauge the quality rather than the size of an audience — verified followers are a better credibility signal than raw follower count. Cursor-paginated. Takes a numeric `user_id`, not a @handle; resolve the handle first with `get_twitter_user_info`. For the complete follower list use `get_twitter_user_followers`.", "parameters": [ { "name": "user_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "User ID of the user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The cursor to paginate through the results. First page is empty." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedFollowersResponse" } } } } } } } } }