# Xpoz - TikTok Scraper (`xpoz/xpoz-tiktok-scraper`) Actor Access TikTok data — users, posts, comments, hashtag search, keyword search, and more. - **URL**: https://apify.com/xpoz/xpoz-tiktok-scraper.md - **Developed by:** [Xpoz](https://apify.com/xpoz) (community) - **Categories:** Social media, Agents, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% 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 - TikTok Scraper Access TikTok data through the [Xpoz](https://xpoz.ai) platform. Search for users, posts, comments, hashtags, and more — all from a single Apify Actor. ### 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 and action 4. **Download results** from the Apify dataset as JSON, CSV, or Excel ### Actions | Action | Description | | -------------------- | ------------------------------------------- | | `getUser` | Get a single user profile by username or ID | | `searchUsers` | Search users by name | | `getUsersByKeywords` | Find users matching keywords in their bio | | `getUsersByHashtags` | Find users posting with specific hashtags | | `getPostsByIds` | Get specific TikTok posts by their IDs | | `getPostsByUser` | Get all posts by a specific user | | `searchPosts` | Search TikTok posts by keywords | | `getPostsByHashtags` | Get posts with specific hashtags | | `getComments` | Get comments on a specific post | ### Input Parameters | Parameter | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------------------------------------------- | | `apiKey` | string | Yes | Your Xpoz API key | | `action` | string | Yes | Action to perform (see table above) | | `identifier` | string | Depends | Username, post ID, or search query depending on the action | | `identifiers` | string[] | Depends | Multiple post IDs (for `getPostsByIds`) | | `identifierType` | string | No | `username` (default) or `id` | | `hashtags` | string[] | Depends | Hashtags without # (for `getUsersByHashtags`, `getPostsByHashtags`) | | `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) | ### Example Use Cases **Find trending creators by hashtag:** - Action: `getUsersByHashtags` | Hashtags: `trending, viral` | Limit: `50` **Search TikTok posts by hashtag:** - Action: `getPostsByHashtags` | Hashtags: `fitness, workout` | Start Date: `2025-01-01` **Analyze content from a specific creator:** - Action: `getPostsByUser` | Identifier: `charlidamelio` | Fetch All Pages: `true` **Monitor competitor activity:** - Action: `getPostsByUser` | Identifier: `competitor_username` | Force Latest: `true` **Search for niche creators:** - Action: `getUsersByKeywords` | Identifier: `plant based recipes` | Limit: `100` ### 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). ## `action` (type: `string`): The TikTok action to perform. ## `identifier` (type: `string`): A username, post ID, or search query depending on the selected action. ## `identifiers` (type: `array`): Multiple post IDs. Used by getPostsByIds. ## `identifierType` (type: `string`): Whether the identifier is a username or numeric ID. ## `hashtags` (type: `array`): Hashtags without # (e.g. trending, viral). Used by getUsersByHashtags and getPostsByHashtags. ## `startDate` (type: `string`): Filter results from this date (ISO 8601 format, e.g. 2024-01-01). ## `endDate` (type: `string`): Filter results until this date (ISO 8601 format, e.g. 2024-12-31). ## `limit` (type: `integer`): Maximum number of results to return. ## `fields` (type: `array`): Specific fields to include in the response. Leave empty for all fields. ## `forceLatest` (type: `boolean`): Force fetching the latest data instead of cached results. ## `fetchAllPages` (type: `boolean`): Automatically fetch all pages of paginated results. ## Actor input object example ```json { "action": "getUser", "identifier": "tiktok", "identifierType": "username", "forceLatest": false, "fetchAllPages": 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 = { "action": "getUser", "identifier": "tiktok" }; // Run the Actor and wait for it to finish const run = await client.actor("xpoz/xpoz-tiktok-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 = { "action": "getUser", "identifier": "tiktok", } # Run the Actor and wait for it to finish run = client.actor("xpoz/xpoz-tiktok-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 '{ "action": "getUser", "identifier": "tiktok" }' | apify call xpoz/xpoz-tiktok-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=xpoz/xpoz-tiktok-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Xpoz - TikTok Scraper", "description": "Access TikTok data — users, posts, comments, hashtag search, keyword search, and more.", "version": "1.0", "x-build-id": "XVT2vDcXO4KpD0JVd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/xpoz~xpoz-tiktok-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-xpoz-xpoz-tiktok-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-tiktok-scraper/runs": { "post": { "operationId": "runs-sync-xpoz-xpoz-tiktok-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-tiktok-scraper/run-sync": { "post": { "operationId": "run-sync-xpoz-xpoz-tiktok-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": [ "action" ], "properties": { "apiKey": { "title": "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)." }, "action": { "title": "Action", "enum": [ "getUser", "searchUsers", "getUsersByKeywords", "getUsersByHashtags", "getPostsByIds", "getPostsByUser", "searchPosts", "getPostsByHashtags", "getComments" ], "type": "string", "description": "The TikTok action to perform." }, "identifier": { "title": "Identifier", "type": "string", "description": "A username, post ID, or search query depending on the selected action." }, "identifiers": { "title": "Identifiers", "type": "array", "description": "Multiple post IDs. Used by getPostsByIds.", "items": { "type": "string" } }, "identifierType": { "title": "Identifier Type", "enum": [ "username", "id" ], "type": "string", "description": "Whether the identifier is a username or numeric ID.", "default": "username" }, "hashtags": { "title": "Hashtags", "type": "array", "description": "Hashtags without # (e.g. trending, viral). Used by getUsersByHashtags and getPostsByHashtags.", "items": { "type": "string" } }, "startDate": { "title": "Start Date", "type": "string", "description": "Filter results from this date (ISO 8601 format, e.g. 2024-01-01)." }, "endDate": { "title": "End Date", "type": "string", "description": "Filter results until this date (ISO 8601 format, e.g. 2024-12-31)." }, "limit": { "title": "Limit", "minimum": 1, "type": "integer", "description": "Maximum number of results to return." }, "fields": { "title": "Fields", "type": "array", "description": "Specific fields to include in the response. Leave empty for all fields.", "items": { "type": "string" } }, "forceLatest": { "title": "Force Latest", "type": "boolean", "description": "Force fetching the latest data instead of cached results.", "default": false }, "fetchAllPages": { "title": "Fetch All Pages", "type": "boolean", "description": "Automatically fetch all pages of paginated 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 } } } } } } } } } } ```