{ "openapi": "3.0.3", "info": { "title": "Twitter API", "version": "1.0.0", "description": "Twitter data API, providing endpoints for user and tweet information." }, "servers": [ { "url": "https://api.aisa.one/apis/v1" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "UserProfileAboutResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "userName": { "type": "string" }, "createdAt": { "type": "string" }, "isBlueVerified": { "type": "boolean" }, "protected": { "type": "boolean" }, "affiliates_highlighted_label": { "type": "object", "properties": { "label": { "type": "object", "properties": { "badge": { "type": "object", "properties": { "url": { "type": "string" } } }, "description": { "type": "string" }, "url": { "type": "object", "properties": { "url": { "type": "string" }, "urlType": { "type": "string" } } }, "userLabelDisplayType": { "type": "string" }, "userLabelType": { "type": "string" } } } } }, "about_profile": { "type": "object", "properties": { "account_based_in": { "type": "string" }, "location_accurate": { "type": "boolean" }, "learn_more_url": { "type": "string" }, "affiliate_username": { "type": "string" }, "source": { "type": "string" }, "username_changes": { "type": "object", "properties": { "count": { "type": "string" } } } } }, "identity_profile_labels_highlighted_label": { "type": "object", "properties": { "label": { "type": "object", "properties": { "description": { "type": "string" }, "badge": { "type": "object", "properties": { "url": { "type": "string" } } }, "url": { "type": "object", "properties": { "url": { "type": "string" }, "urlType": { "type": "string" } } }, "userLabelDisplayType": { "type": "string" }, "userLabelType": { "type": "string" } } } } } } }, "status": { "type": "string", "enum": [ "success", "error" ] }, "msg": { "type": "string" } } }, "BatchUserInfoResponse": { "type": "object", "properties": { "users": { "type": "array", "items": { "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" } } } }, "status": { "type": "string", "enum": [ "success", "error" ] }, "msg": { "type": "string" } } }, "UserTweetsResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success", "error" ] }, "code": { "type": "integer", "description": "Provider status code returned by the AIsa wrapper." }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "tweets": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Tweet object returned by TwitterAPI.io." } }, "pin_tweet": { "type": "object", "nullable": true, "additionalProperties": true } }, "additionalProperties": true }, "has_next_page": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "UserInfoResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success", "error" ] }, "msg": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "description": "User profile object returned by TwitterAPI.io." } } }, "UserFollowersResponse": { "type": "object", "properties": { "followers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Follower user object returned by TwitterAPI.io." } }, "has_next_page": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "success", "error" ] }, "msg": { "type": "string" }, "code": { "type": "integer" } } } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/twitter/user_about": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 1", "nominal_usd": 0.00044, "observed_usd": { "min": 0.00018, "p50": 0.00044, "p95": 0.00044, "max": 0.00044 }, "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_about" ], "summary": "Get User Profile About", "operationId": "get_twitter_user_about", "description": "Get the extended 'About this account' panel for an X user by @handle. Use this for provenance and trust checks — it surfaces signals the standard profile does not, such as the account's country, verification details, and username-change history. Returns a single profile object under `data`. For the standard profile (bio, follower counts, avatar), use `get_twitter_user_info` instead.", "parameters": [ { "name": "userName", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The screen name of the user" } ], "responses": { "200": { "description": "User profile information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileAboutResponse" } } } } } } }, "/twitter/user/batch_info_by_ids": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 2", "nominal_usd": 0.00044, "observed_usd": { "min": 0.00036, "p50": 0.00044, "p95": 0.00044, "max": 0.0334 }, "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/batch_get_user_by_userids" ], "summary": "Batch Get User Info By UserIds", "operationId": "get_twitter_user_batch_info_by_ids", "description": "Resolve many X users at once from their numeric user IDs, passed as a comma-separated `userIds` string. Use this when a previous call (timeline, retweeters, followers) gave you IDs and you need to turn them into full profiles in one request instead of looping. Returns an array of user objects under `users`. Note this endpoint takes numeric IDs, not @handles — to look up by handle use `get_twitter_user_info`.", "parameters": [ { "name": "userIds", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated user IDs" } ], "responses": { "200": { "description": "Batch user information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUserInfoResponse" } } } } } } }, "/twitter/user/info": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 1", "nominal_usd": 0.00044, "observed_usd": { "min": 0.00018, "p50": 0.00044, "p95": 0.00044, "max": 0.00044 }, "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_by_username" ], "summary": "Get User Info", "operationId": "get_twitter_user_info", "description": "Look up one X (Twitter) user's public profile by @handle (screen name). Use this when you need to know who an account is — identity, reach, or credibility — before deciding whether to trust or analyze their content. Returns display name, bio, follower/following counts, verification status, account creation date, location, and profile images. If you only have a numeric user ID, use `get_twitter_user_batch_info_by_ids` instead. If you need extended profile metadata such as country or username-change history, use `get_twitter_user_about`. If you want their posts rather than their profile, use `get_twitter_user_tweet_timeline`.", "parameters": [ { "name": "userName", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The screen name of the user" } ], "responses": { "200": { "description": "User information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoResponse" } } } } } } }, "/twitter/user/tweet_timeline": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 2", "nominal_usd": 0.0036, "observed_usd": { "min": 0.00015, "p50": 0.0036, "p95": 0.0036, "max": 0.0114 }, "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_timeline" ], "summary": "Get User Tweet Timeline", "operationId": "get_twitter_user_tweet_timeline", "description": "Retrieve a user's own tweets by numeric `userId`, newest first, matching the order shown on their profile in the X app. Up to 20 tweets per page; pass the returned cursor for more. Optionally include replies and the parent tweet of each reply. Use this to read what an account publishes over time. Time-range filtering is NOT supported here — if you need tweets within a specific time window, use `get_twitter_user_mentions` (which accepts `sinceTime`/`untilTime`) or `get_twitter_tweet_advanced_search` with date operators in the query. If you only have a @handle, `get_twitter_user_last_tweets` accepts either handle or ID.", "parameters": [ { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "User ID of the user whose timeline to retrieve." }, { "name": "includeReplies", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to include replies in the results. Defaults to false." }, { "name": "includeParentTweet", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to include the parent tweet when a tweet is a reply. Defaults to false." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for paginating through results. Leave empty for the first page." } ], "responses": { "200": { "description": "User tweet timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTweetsResponse" } } } } } } }, "/twitter/user/last_tweets": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 2", "nominal_usd": 0.0036, "observed_usd": { "min": 0.00015, "p50": 0.0036, "p95": 0.006, "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_last_tweets" ], "summary": "Get User Last Tweets", "operationId": "get_twitter_user_last_tweets", "description": "Get a user's most recent tweets, accepting either `userName` (@handle) or `userId` — useful when you have not resolved the handle to an ID yet. Optionally include replies. Cursor-paginated. Returns tweets under `data` with `has_next_page` and `next_cursor`. Use `get_twitter_user_tweet_timeline` instead when you already have the numeric ID and want the full profile-order timeline with parent-tweet expansion.", "parameters": [ { "name": "userId", "in": "query", "schema": { "type": "string" }, "description": "User ID of the user" }, { "name": "userName", "in": "query", "schema": { "type": "string" }, "description": "Screen name of the user" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination" }, { "name": "includeReplies", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include replies in the results" } ], "responses": { "200": { "description": "User tweets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTweetsResponse" } } } } } } }, "/twitter/user/followers": { "get": { "x-aisa-pricing": { "model": "dynamic", "currency": "USD", "basis": "provider_cost x 2", "nominal_usd": 0.036, "observed_usd": { "min": 0.0006, "p50": 0.002, "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_followers" ], "summary": "Get User Followers", "operationId": "get_twitter_user_followers", "description": "List the accounts that follow a given X user, identified by @handle, newest follower first. Returns up to 200 per page by default with `has_next_page` and `next_cursor`; each entry is a full user object (handle, name, bio, follower count, verification). Use this for audience analysis, mapping a competitor's follower base, or finding influential followers. For the reverse direction (who this user follows) use `get_twitter_user_followings`. For only the verified subset use `get_twitter_user_verified_followers` — note that one takes a numeric `user_id`, not a handle.", "parameters": [ { "name": "userName", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Screen name of the user" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination" }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 200, "minimum": 20, "maximum": 200 }, "description": "Number of followers per page" } ], "responses": { "200": { "description": "User followers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFollowersResponse" } } } } } } } } }