{ "openapi": "3.1.0", "info": { "title": "XCROP — X (Twitter) Data Intelligence API", "version": "2.0.0", "description": "REST API for real-time X/Twitter data: tweet & user search, profile and follower analytics, tweet lookups, trending topics, interaction verification, and a full Write API. Credit-based pricing up to 50% cheaper than alternatives. Authenticate with `Authorization: Bearer xc_live_...`. Responses are JSON with a `data` payload and a `meta` object (pagination cursor + latency). See https://xcrop.io/docs.", "termsOfService": "https://xcrop.io/legal/terms", "contact": { "name": "XCROP", "url": "https://xcrop.io/contact", "email": "support@xcrop.io" } }, "servers": [ { "url": "https://xcrop.io/api", "description": "Production" } ], "externalDocs": { "description": "Full documentation", "url": "https://xcrop.io/docs" }, "tags": [ { "name": "Search", "description": "Search endpoints" }, { "name": "Users", "description": "Users endpoints" }, { "name": "Interaction Check", "description": "Interaction Check endpoints" }, { "name": "Tweets", "description": "Tweets endpoints" }, { "name": "Lists", "description": "Lists endpoints" }, { "name": "Communities", "description": "Communities endpoints" }, { "name": "Analytics", "description": "Analytics endpoints" }, { "name": "Write API", "description": "Write API endpoints" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v2/search": { "post": { "operationId": "postSearch", "summary": "Search tweets across accounts and trending topics", "tags": [ "Search" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Query (e.g. $BTC breakout)" }, "count": { "type": "integer", "description": "Count (default 20 · up to 1000)" }, "sort": { "type": "string", "enum": [ "latest", "popular", "engagement" ], "description": "Sort By" }, "lang": { "type": "string", "description": "Language (e.g. en, vi, ja (optional))" }, "min_likes": { "type": "integer", "description": "Min Likes (optional)" }, "min_retweets": { "type": "integer", "description": "Min Retweets (optional)" }, "include_replies": { "type": "boolean", "description": "Include Replies" }, "include_retweets": { "type": "boolean", "description": "Include Retweets" } }, "required": [ "query" ] } } } } } }, "/v2/search/users": { "post": { "operationId": "postSearchUsers", "summary": "Search for users by name, bio, or username", "tags": [ "Search" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 18, "unit": "profile", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Query (e.g. crypto trader)" }, "count": { "type": "integer", "description": "Count (default 20 · up to 1000)" }, "sort": { "type": "string", "enum": [ "default", "followers", "name" ], "description": "Sort By" } }, "required": [ "query" ] } } } } } }, "/v2/users/{username}": { "get": { "operationId": "getUsersByUsername", "summary": "Look up a Twitter/X user profile by username", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 18, "unit": "profile", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" } ] } }, "/v2/users/{username}/tweets": { "get": { "operationId": "getUsersByUsernameTweets", "summary": "Fetch recent tweets from a user with engagement metrics", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "latest", "popular", "engagement" ] }, "description": "Sort By" } ] } }, "/v2/users/{username}/mentions": { "get": { "operationId": "getUsersByUsernameMentions", "summary": "Get tweets mentioning a specific user", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "latest", "popular", "engagement" ] }, "description": "Sort By" } ] } }, "/v2/users/{username}/followers": { "get": { "operationId": "getUsersByUsernameFollowers", "summary": "Get a list of followers for a user", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 1, "unit": "follower", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "followers", "name" ] }, "description": "Sort By" } ] } }, "/v2/users/{username}/followers-ids": { "get": { "operationId": "getUsersByUsernameFollowersIds", "summary": "Bulk-fetch follower IDs — up to 5,000 per call, no profile metadata (for large-scale ID collection)", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 1, "unit": "follower", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (max 5000)" } ] } }, "/v2/users/{username}/following": { "get": { "operationId": "getUsersByUsernameFollowing", "summary": "Get a list of accounts a user is following", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 1, "unit": "follower", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "followers", "name" ] }, "description": "Sort By" } ] } }, "/v2/users/{username}/replies": { "get": { "operationId": "getUsersByUsernameReplies", "summary": "Get tweets and replies from a user timeline", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "latest", "popular", "engagement" ] }, "description": "Sort By" } ] } }, "/v2/users/{username}/media": { "get": { "operationId": "getUsersByUsernameMedia", "summary": "Get media tweets (photos, videos) from a user", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "latest", "popular", "engagement" ] }, "description": "Sort By" } ] } }, "/v2/users/{username}/verified-followers": { "get": { "operationId": "getUsersByUsernameVerifiedFollowers", "summary": "Get blue-verified followers of a user", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 1, "unit": "follower", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "followers", "name" ] }, "description": "Sort By" } ] } }, "/v2/users/batch": { "post": { "operationId": "postUsersBatch", "summary": "Look up multiple users by username in a single request (max 100)", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 18, "unit": "profile", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "usernames": { "type": "array", "items": { "type": "string" }, "description": "Usernames (comma-separated, e.g. elonmusk,VitalikButerin)" } }, "required": [ "usernames" ] } } } } } }, "/v2/tweets/{tweetId}": { "get": { "operationId": "getTweetsByTweetId", "summary": "Look up a single tweet by its ID", "tags": [ "Tweets" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" } ] }, "delete": { "operationId": "deleteTweetsByTweetId", "summary": "Delete a tweet (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" } ] } }, "/v2/tweets/{tweetId}/conversation": { "get": { "operationId": "getTweetsByTweetIdConversation", "summary": "Get the conversation thread for a tweet", "tags": [ "Tweets" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "latest", "popular", "engagement" ] }, "description": "Sort By" } ] } }, "/v2/tweets/{tweetId}/quotes": { "get": { "operationId": "getTweetsByTweetIdQuotes", "summary": "Get quote tweets of a specific tweet", "tags": [ "Tweets" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "latest", "popular", "engagement" ] }, "description": "Sort By" } ] } }, "/v2/tweets/batch": { "post": { "operationId": "postTweetsBatch", "summary": "Look up multiple tweets by ID in a single request (max 100)", "tags": [ "Tweets" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Tweet IDs (comma-separated IDs)" } }, "required": [ "ids" ] } } } } } }, "/v2/lists/{listId}/tweets": { "get": { "operationId": "getListsByListIdTweets", "summary": "Get latest tweets from a Twitter/X list", "tags": [ "Lists" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "listId" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "latest", "popular", "engagement" ] }, "description": "Sort By" } ] } }, "/v2/lists/{listId}/members": { "get": { "operationId": "getListsByListIdMembers", "summary": "Get members of a Twitter/X list", "tags": [ "Lists" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 1, "unit": "follower", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "listId" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "followers", "name" ] }, "description": "Sort By" } ] } }, "/v2/lists/{listId}/subscribers": { "get": { "operationId": "getListsByListIdSubscribers", "summary": "Get subscribers of a Twitter/X list", "tags": [ "Lists" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 1, "unit": "follower", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "listId" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "followers", "name" ] }, "description": "Sort By" } ] } }, "/v2/communities/{communityId}": { "get": { "operationId": "getCommunitiesByCommunityId", "summary": "Get community details by ID (Under Development — may return 503)", "tags": [ "Communities" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 18, "unit": "profile", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "communityId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "communityId" } ] } }, "/v2/communities/{communityId}/tweets": { "get": { "operationId": "getCommunitiesByCommunityIdTweets", "summary": "Get tweets from a community timeline (Under Development — may return 503)", "tags": [ "Communities" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 15, "unit": "tweet", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "communityId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "communityId" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "latest", "popular", "engagement" ] }, "description": "Sort By" } ] } }, "/v2/communities/{communityId}/members": { "get": { "operationId": "getCommunitiesByCommunityIdMembers", "summary": "Get members of a community (Under Development — may return 503)", "tags": [ "Communities" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 1, "unit": "follower", "perResult": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "communityId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "communityId" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Count (default 20 · up to 1000)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "followers", "name" ] }, "description": "Sort By" } ] } }, "/v2/trending": { "get": { "operationId": "getTrending", "summary": "Real-time trending topics from Twitter — \"What's happening\"", "tags": [ "Analytics" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Worldwide", "Algeria", "Argentina", "Australia", "Austria", "Bahrain", "Belarus", "Belgium", "Brazil", "Canada", "Chile", "Colombia", "Denmark", "Dominican Republic", "Ecuador", "Egypt", "France", "Germany", "Ghana", "Greece", "Guatemala", "India", "Indonesia", "Ireland", "Israel", "Italy", "Japan", "Jordan", "Kenya", "Korea", "Kuwait", "Latvia", "Lebanon", "Malaysia", "Mexico", "Netherlands", "New Zealand", "Nigeria", "Norway", "Oman", "Pakistan", "Panama", "Peru", "Philippines", "Poland", "Portugal", "Puerto Rico", "Qatar", "Russia", "Saudi Arabia", "Singapore", "South Africa", "Spain", "Sweden", "Switzerland", "Thailand", "Turkey", "Ukraine", "United Arab Emirates", "United Kingdom", "United States", "Venezuela", "Vietnam" ] }, "description": "Country" } ] } }, "/v2/tweets/create": { "post": { "operationId": "postTweetsCreate", "summary": "Create a new tweet (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Tweet Text (e.g. Hello from XCROP API!)" } }, "required": [ "text" ] } } } } } }, "/v2/tweets/reply": { "post": { "operationId": "postTweetsReply", "summary": "Reply to a tweet (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tweet_id": { "type": "string", "description": "Tweet URL or ID (e.g. 2028524112868708616)" }, "text": { "type": "string", "description": "Reply Text (e.g. Great thread!)" } }, "required": [ "tweet_id", "text" ] } } } } } }, "/v2/tweets/quote": { "post": { "operationId": "postTweetsQuote", "summary": "Quote-tweet (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoted_tweet_id": { "type": "string", "description": "Quoted Tweet ID (e.g. 2028524112868708616)" }, "text": { "type": "string", "description": "Quote Text (e.g. Interesting take)" } }, "required": [ "quoted_tweet_id", "text" ] } } } } } }, "/v2/tweets/{tweetId}/like": { "post": { "operationId": "postTweetsByTweetIdLike", "summary": "Like a tweet (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" } ] }, "delete": { "operationId": "deleteTweetsByTweetIdLike", "summary": "Unlike a tweet (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" } ] } }, "/v2/tweets/{tweetId}/retweet": { "post": { "operationId": "postTweetsByTweetIdRetweet", "summary": "Retweet a tweet (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" } ] }, "delete": { "operationId": "deleteTweetsByTweetIdRetweet", "summary": "Unretweet a tweet (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" } ] } }, "/v2/users/{username}/follow": { "post": { "operationId": "postUsersByUsernameFollow", "summary": "Follow a user (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" } ] }, "delete": { "operationId": "deleteUsersByUsernameFollow", "summary": "Unfollow a user (requires connected X account)", "tags": [ "Write API" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 100, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" } ] } }, "/v2/users/check-follow": { "get": { "operationId": "getUsersCheckFollow", "summary": "Check follow relationship between two users", "tags": [ "Interaction Check" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 50, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Source Username (e.g. elonmusk)" }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Target Username (e.g. VitalikButerin)" } ] } }, "/v2/tweets/{tweetId}/check-retweet": { "get": { "operationId": "getTweetsByTweetIdCheckRetweet", "summary": "Check if a user has retweeted a tweet", "tags": [ "Interaction Check" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 50, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" }, { "name": "username", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Username (e.g. elonmusk)" } ] } }, "/v2/tweets/{tweetId}/check-reply": { "get": { "operationId": "getTweetsByTweetIdCheckReply", "summary": "Check if a user has replied to a tweet", "tags": [ "Interaction Check" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 50, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" }, { "name": "username", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Username (e.g. elonmusk)" }, { "name": "min_tags", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Min Tags (friends) (optional)" } ] } }, "/v2/tweets/{tweetId}/check-quote": { "get": { "operationId": "getTweetsByTweetIdCheckQuote", "summary": "Check if a user has quoted a tweet", "tags": [ "Interaction Check" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 50, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "tweetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "tweetId" }, { "name": "username", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Username (e.g. elonmusk)" }, { "name": "min_tags", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Min Tags (friends) (optional)" } ] } }, "/v2/users/{username}/check-qualified-account": { "get": { "operationId": "getUsersByUsernameCheckQualifiedAccount", "summary": "Eligibility check: does the account meet minimum followers + minimum account age (days)? For giveaway/airdrop gating.", "tags": [ "Interaction Check" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 50, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "min_followers", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Min Followers (e.g. 100)" }, { "name": "min_age_days", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Min Account Age (days) (e.g. 30)" } ] } }, "/v2/users/{username}/check-qualified-name": { "get": { "operationId": "getUsersByUsernameCheckQualifiedName", "summary": "Eligibility check: does the account display name contain a required text (anywhere, left, or right)? For giveaway gating.", "tags": [ "Interaction Check" ], "security": [ { "bearerAuth": [] } ], "x-credit-cost": { "credits": 50, "unit": "call", "perResult": false }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "username" }, { "name": "contains", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Contains Text (e.g. crypto)" }, { "name": "position", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "anywhere", "left", "right" ] }, "description": "Position" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "xc_live_… API key", "description": "API key issued in the XCROP dashboard, sent as a Bearer token." } }, "schemas": { "SuccessResponse": { "type": "object", "properties": { "data": { "description": "Endpoint payload — an object or array depending on the endpoint." }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "next_cursor": { "type": "string", "nullable": true }, "has_next_page": { "type": "boolean" }, "latency_ms": { "type": "integer" } } } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } }, "responses": { "Error": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }