# Xpoz - Social Media Scraper (`xpoz/xpoz-social-media-scraper`) Actor Access Twitter/X, Instagram, Reddit, and TikTok data — users, posts, comments, followers, keyword search, and more. - **URL**: https://apify.com/xpoz/xpoz-social-media-scraper.md - **Developed by:** [Xpoz](https://apify.com/xpoz) (community) - **Categories:** Social media, Lead generation, Agents - **Stats:** 3 total users, 1 monthly users, 58.3% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Xpoz - Social Media Intelligence Access data from **Twitter/X**, **Instagram**, **Reddit**, and **TikTok** through the Xpoz platform. Search for users, posts, comments, followers, and more — all from a single Apify Actor. ### What is Xpoz? [Xpoz](https://xpoz.ai) is a social media intelligence platform that provides structured access to data across major social networks. This Actor wraps the Xpoz TypeScript SDK to make all capabilities available directly from Apify. ### Getting Started 1. **Try it now** — run the Actor without an API key to get a preview with limited results (max 5) and narrower data coverage 2. **Get an API key** at [xpoz.ai/get-token](https://xpoz.ai/get-token) for full access with unlimited results and optimal data coverage 3. **Run this Actor** with your API key, platform, and action 4. **Download results** from the Apify dataset as JSON, CSV, or Excel ### Supported Platforms & Actions #### Twitter / X | Action | Description | | ------------------------- | ----------------------------------------------------- | | `getUser` | Get a single user profile by username or ID | | `getUsers` | Get multiple user profiles at once | | `searchUsers` | Search users by name | | `getUserConnections` | Get a user's followers or following list | | `getUsersByKeywords` | Find users by keyword search | | `getPostsByIds` | Get specific tweets by their IDs | | `getPostsByAuthor` | Get all tweets by a specific user | | `searchPosts` | Search tweets by keywords | | `getRetweets` | Get retweets of a specific tweet | | `getQuotes` | Get quote tweets of a specific tweet | | `getComments` | Get replies to a specific tweet | | `getPostInteractingUsers` | Get users who liked, retweeted, or replied to a tweet | | `countPosts` | Count tweets matching a search query | #### Instagram | Action | Description | | ------------------------- | ---------------------------------------- | | `getUser` | Get a user profile by username or ID | | `searchUsers` | Search users by name | | `getUserConnections` | Get a user's followers or following list | | `getPostInteractingUsers` | Get users who interacted with a post | | `getUsersByKeywords` | Find users by keyword search | | `getPostsByIds` | Get specific posts by their IDs | | `getPostsByUser` | Get all posts by a specific user | | `searchPosts` | Search posts by keywords | | `getComments` | Get comments on a specific post | #### Reddit | Action | Description | | ------------------------- | --------------------------------------- | | `getUser` | Get a user profile | | `searchUsers` | Search users by name | | `getUsersByKeywords` | Find users by keyword search | | `searchSubreddits` | Search subreddits by name | | `getSubredditsByKeywords` | Find subreddits by keyword search | | `getSubredditWithPosts` | Get a subreddit's info and recent posts | | `searchPosts` | Search posts by keywords | | `getPostWithComments` | Get a post and its comments | | `searchComments` | Search comments by keywords | #### TikTok | Action | Description | | -------------------- | ----------------------------------------- | | `getUser` | Get a user profile by username or ID | | `searchUsers` | Search users by name | | `getUsersByKeywords` | Find users by keyword search | | `getUsersByHashtags` | Find users posting with specific hashtags | | `getPostsByIds` | Get specific posts by their IDs | | `getPostsByUser` | Get all posts by a specific user | | `searchPosts` | Search posts by keywords | | `getPostsByHashtags` | Get posts with specific hashtags | | `getComments` | Get comments on a specific post | #### Tracking | Action | Description | | -------------------- | --------------------------------------------------- | | `getTrackedItems` | List all your tracked keywords, users, and hashtags | | `addTrackedItems` | Add items to your tracking list | | `removeTrackedItems` | Remove items from your tracking list | ### Input Parameters | Parameter | Type | Required | Description | | ------------------- | -------- | -------- | ------------------------------------------------------------------- | | `apiKey` | string | Yes | Your Xpoz API key | | `platform` | string | Yes | Platform: `twitter`, `instagram`, `reddit`, `tiktok`, or `tracking` | | `action` | string | Yes | Action to perform (see tables above) | | `identifier` | string | Depends | Username, post ID, search query, or subreddit name | | `identifiers` | string[] | Depends | Multiple IDs (for `getUsers`, `getPostsByIds`) | | `identifierType` | string | No | `username` (default) or `id` | | `connectionType` | string | Depends | `followers` or `following` (for `getUserConnections`) | | `interactionType` | string | Depends | `likes`, `retweets`, `replies`, or `comments` | | `hashtags` | string[] | Depends | Hashtags without # (for TikTok hashtag actions) | | `subreddit` | string | No | Filter Reddit results to a specific subreddit | | `startDate` | string | No | Start date filter (YYYY-MM-DD) | | `endDate` | string | No | End date filter (YYYY-MM-DD) | | `limit` | integer | No | Maximum number of results | | `fields` | string[] | No | Specific fields to include (empty = all) | | `forceLatest` | boolean | No | Force fresh data instead of cached | | `fetchAllPages` | boolean | No | Fetch all pages of results (default: first page only) | | `sort` | string | No | Reddit sort order: `new`, `hot`, `top`, `controversial`, `rising` | | `time` | string | No | Reddit time range: `hour`, `day`, `week`, `month`, `year`, `all` | | `language` | string | No | Language code filter (e.g., `en`, `es`) | | `filterOutRetweets` | boolean | No | Exclude retweets from Twitter search | ### Example Use Cases **Find influencers talking about AI on Twitter:** - Platform: `twitter` | Action: `getUsersByKeywords` | Identifier: `artificial intelligence` | Start Date: `2025-01-01` **Export all posts from an Instagram account:** - Platform: `instagram` | Action: `getPostsByUser` | Identifier: `natgeo` | Fetch All Pages: `true` **Monitor Reddit discussions about your brand:** - Platform: `reddit` | Action: `searchPosts` | Identifier: `your brand name` | Sort: `new` **Get trending TikTok content by hashtag:** - Platform: `tiktok` | Action: `getPostsByHashtags` | Hashtags: `trending, viral` ### Output Results are pushed to the default Apify dataset. Each item in the dataset corresponds to a user, post, comment, or other entity depending on the action. Download results as JSON, CSV, or Excel from the Apify console. For paginated results, pagination metadata (total rows, total pages) is stored in the key-value store under the key `PAGINATION_INFO`. ### Pricing **This Actor is free.** You only pay for Apify platform usage (compute time) and your Xpoz API plan. The Actor is usable without an API key, but results will be very limited (max 5 items per request) with narrower data coverage. Get your API key at [xpoz.ai/get-token](https://xpoz.ai/get-token) for unlimited results and optimal data coverage. ### Support - Xpoz documentation: [docs.xpoz.ai](https://docs.xpoz.ai) - Email: support@xpoz.ai # Actor input Schema ## `apiKey` (type: `string`): Your Xpoz API key. Get one at https://xpoz.ai/get-token. If not provided, the Actor runs with limited public access (max 5 results). ## `platform` (type: `string`): The social media platform to query. ## `action` (type: `string`): The action to perform on the selected platform. ## `identifier` (type: `string`): The primary identifier for the action — a username, post ID, search query, or subreddit name depending on the action. ## `identifiers` (type: `array`): Multiple identifiers — user IDs, post IDs, or usernames. Used by getUsers, getPostsByIds, and similar multi-ID actions. ## `identifierType` (type: `string`): How to interpret the identifier — as a username or numeric ID. ## `connectionType` (type: `string`): Type of user connections to retrieve. ## `interactionType` (type: `string`): Type of post interaction to retrieve users for. ## `hashtags` (type: `array`): Hashtags to search for (without #). Used by TikTok hashtag actions. ## `subreddit` (type: `string`): Subreddit name to filter results (without r/). ## `trackedItems` (type: `array`): Items to add or remove from tracking. Each item needs phrase, type (keyword/user/subreddit/hashtag), and platform. ## `startDate` (type: `string`): Filter results from this date (YYYY-MM-DD). ## `endDate` (type: `string`): Filter results until this date (YYYY-MM-DD). ## `limit` (type: `integer`): Maximum number of results to return. ## `fields` (type: `array`): Specific fields to include in results. Leave empty for all fields. ## `forceLatest` (type: `boolean`): Force fetching the latest data from the source instead of using cached results. ## `fetchAllPages` (type: `boolean`): For paginated results, fetch all pages instead of just the first page. ## `sort` (type: `string`): Sort order for Reddit results. ## `time` (type: `string`): Time range filter for Reddit results. ## `language` (type: `string`): Filter results by language code (e.g., 'en', 'es', 'fr'). ## `filterOutRetweets` (type: `boolean`): Exclude retweets from Twitter search results. ## Actor input object example ```json { "platform": "twitter", "action": "getUser", "identifier": "elonmusk", "identifierType": "username", "forceLatest": false, "fetchAllPages": false, "filterOutRetweets": false } ```` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "platform": "twitter", "action": "getUser", "identifier": "elonmusk" }; // Run the Actor and wait for it to finish const run = await client.actor("xpoz/xpoz-social-media-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "platform": "twitter", "action": "getUser", "identifier": "elonmusk", } # Run the Actor and wait for it to finish run = client.actor("xpoz/xpoz-social-media-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "platform": "twitter", "action": "getUser", "identifier": "elonmusk" }' | apify call xpoz/xpoz-social-media-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=xpoz/xpoz-social-media-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Xpoz - Social Media Scraper", "description": "Access Twitter/X, Instagram, Reddit, and TikTok data — users, posts, comments, followers, keyword search, and more.", "version": "1.0", "x-build-id": "hhaxstYIHqDiAfqVr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/xpoz~xpoz-social-media-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-xpoz-xpoz-social-media-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/xpoz~xpoz-social-media-scraper/runs": { "post": { "operationId": "runs-sync-xpoz-xpoz-social-media-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/xpoz~xpoz-social-media-scraper/run-sync": { "post": { "operationId": "run-sync-xpoz-xpoz-social-media-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "platform", "action" ], "properties": { "apiKey": { "title": "Xpoz API Key", "type": "string", "description": "Your Xpoz API key. Get one at https://xpoz.ai/get-token. If not provided, the Actor runs with limited public access (max 5 results)." }, "platform": { "title": "Platform", "enum": [ "twitter", "instagram", "reddit", "tiktok", "tracking", "account" ], "type": "string", "description": "The social media platform to query." }, "action": { "title": "Action", "enum": [ "getUser", "getUsers", "searchUsers", "getUserConnections", "getUsersByKeywords", "getPostsByIds", "getPostsByAuthor", "searchPosts", "getRetweets", "getQuotes", "getComments", "getPostInteractingUsers", "countPosts", "getPostsByUser", "getPostsByHashtags", "getUsersByHashtags", "getPostWithComments", "searchComments", "searchSubreddits", "getSubredditWithPosts", "getSubredditsByKeywords", "getTrackedItems", "addTrackedItems", "removeTrackedItems", "getAccountDetails" ], "type": "string", "description": "The action to perform on the selected platform." }, "identifier": { "title": "Identifier", "type": "string", "description": "The primary identifier for the action — a username, post ID, search query, or subreddit name depending on the action." }, "identifiers": { "title": "Identifiers (multiple)", "type": "array", "description": "Multiple identifiers — user IDs, post IDs, or usernames. Used by getUsers, getPostsByIds, and similar multi-ID actions.", "items": { "type": "string" } }, "identifierType": { "title": "Identifier Type", "enum": [ "username", "id" ], "type": "string", "description": "How to interpret the identifier — as a username or numeric ID.", "default": "username" }, "connectionType": { "title": "Connection Type", "enum": [ "followers", "following" ], "type": "string", "description": "Type of user connections to retrieve." }, "interactionType": { "title": "Interaction Type", "enum": [ "likes", "retweets", "replies", "comments" ], "type": "string", "description": "Type of post interaction to retrieve users for." }, "hashtags": { "title": "Hashtags", "type": "array", "description": "Hashtags to search for (without #). Used by TikTok hashtag actions.", "items": { "type": "string" } }, "subreddit": { "title": "Subreddit", "type": "string", "description": "Subreddit name to filter results (without r/)." }, "trackedItems": { "title": "Tracked Items", "type": "array", "description": "Items to add or remove from tracking. Each item needs phrase, type (keyword/user/subreddit/hashtag), and platform." }, "startDate": { "title": "Start Date", "type": "string", "description": "Filter results from this date (YYYY-MM-DD)." }, "endDate": { "title": "End Date", "type": "string", "description": "Filter results until this date (YYYY-MM-DD)." }, "limit": { "title": "Result Limit", "minimum": 1, "type": "integer", "description": "Maximum number of results to return." }, "fields": { "title": "Fields", "type": "array", "description": "Specific fields to include in results. Leave empty for all fields.", "items": { "type": "string" } }, "forceLatest": { "title": "Force Latest Data", "type": "boolean", "description": "Force fetching the latest data from the source instead of using cached results.", "default": false }, "fetchAllPages": { "title": "Fetch All Pages", "type": "boolean", "description": "For paginated results, fetch all pages instead of just the first page.", "default": false }, "sort": { "title": "Sort", "enum": [ "new", "hot", "top", "controversial", "rising" ], "type": "string", "description": "Sort order for Reddit results." }, "time": { "title": "Time Range", "enum": [ "hour", "day", "week", "month", "year", "all" ], "type": "string", "description": "Time range filter for Reddit results." }, "language": { "title": "Language", "type": "string", "description": "Filter results by language code (e.g., 'en', 'es', 'fr')." }, "filterOutRetweets": { "title": "Filter Out Retweets", "type": "boolean", "description": "Exclude retweets from Twitter search results.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```