Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ)

Official51 toolsLive

by XPOZpublic · Shell

Twitter/X, Instagram, Reddit & TikTok data for AI agents. Billions of posts. No API keys.

ai.xpoz/social-insights MCP Server

This Model Context Protocol (MCP) server provides access to Twitter/X, Instagram, Reddit, and TikTok data for AI agents. It indexes billions of posts and supports natural-language queries. Export is available as CSV up to 500K rows, and the server is remote (no local installation required). Connections use Streamable HTTP with OAuth 2.1.

🛠️ Key Features

Twitter/X, Instagram, Reddit, and TikTok data
Billions of posts indexed
Natural language queries
CSV exports up to 500K rows
Remote MCP server via Streamable HTTP
OAuth 2.1 authentication (sign in with Google; no API keys)

🚀 Use Cases

Social-media data lookup for AI agents
Querying indexed social content across multiple platforms
Exporting large result sets to CSV (up to 500K rows)

⚡ Developer Benefits

No local installation required
No API keys to manage (OAuth 2.1 instead)
Streamable HTTP connectivity
Multi-platform coverage (Twitter/X, Instagram, Reddit, TikTok)

⚠️ Limitations

Requires OAuth 2.1 authentication for access
Export size limited to CSV up to 500K rows

Topics

ai-agentsinstagram-apimcpmcp-servermodel-context-protocolreddit-apisocial-intelligencesocial-mediatiktoktwitter-api

Captured live from the server via tools/list.

getTwitterUsers

Get one or more Twitter user profiles by IDs or usernames (1-100 per request). Use identifierType="id" for numeric user IDs, identifierType="username" for usernames. All identifiers must be the same type. For single user: pass array of 1, e.g. identifiers=["elonmusk"]. For person names or fuzzy search, use searchTwitterUsers instead. PERFORMANCE: More efficient than multiple single calls, but can still take time for many users. Returns only found users, omitting not-found identifiers for flexibility. Optional fields parameter for performance (default: ["id", "username", "name"]). Available fields: id, profileImageUrl, profileBannerUrl, profileInterstitialType, status, username, verifiedType, name, description, location, protected, verified, followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount, pinnedTweetId, source, nLang, nLangsFiltered, label, labelType, isVerified, modifiedAt, createdAt, verifiedSinceDatetime, accountBasedIn, locationAccurate, usernameChanges, lastUsernameChangeDatetime. NOTE: Use "tweetCount" not "statusesCount". Returns: array of user profiles with count and dataSource. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters9

identifiers	array	required	Array of user IDs (numeric) or usernames (1-100). All must match identifierType. Examples: ["elonmusk", "sama"] for usernames, ["44196397", "123456"] for IDs. Returns only found users, omitting not-found identifiers.
identifierType	string	required	Type of identifier provided. Use "id" for numeric user ID, "username" for username.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "name"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: ["id", "username"] for minimal, ["username", "name", "description, followersCount"] for basic info, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "identifiers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Array of user IDs (numeric) or usernames (1-100). All must match identifierType. Examples: [\"elonmusk\", \"sama\"] for usernames, [\"44196397\", \"123456\"] for IDs. Returns only found users, omitting not-found identifiers."
    },
    "identifierType": {
      "type": "string",
      "enum": [
        "id",
        "username"
      ],
      "description": "Type of identifier provided. Use \"id\" for numeric user ID, \"username\" for username."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"name\"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"name\", \"description, followersCount\"] for basic info, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "identifiers",
    "identifierType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterUser

Get Twitter user profile by ID or username. Use identifierType="id" for numeric user ID, identifierType="username" for username. For username: Use ONLY when you have the precise username (e.g., "elonmusk"). For person names or fuzzy search, use searchTwitterUsers instead. Optional fields parameter for performance (default: ["id", "username", "name"]). Available fields: id, profileImageUrl, profileBannerUrl, profileInterstitialType, status, username, verifiedType, name, description, location, protected, verified, followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount, pinnedTweetId, source, nLang, nLangsFiltered, label, labelType, isVerified, modifiedAt, createdAt, verifiedSinceDatetime, accountBasedIn, locationAccurate, usernameChanges, lastUsernameChangeDatetime. NOTE: Use "tweetCount" not "statusesCount". Returns: single user profile with id, username, name, bio, followers_count, following_count, tweet_count, created_at, authenticity_score, inauthentic_type. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters9

identifier	string	required	User ID (numeric) or username depending on identifierType.
identifierType	string	required	Type of identifier provided. Use "id" for numeric user ID, "username" for username.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "name"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: ["id", "username"] for minimal, ["username", "name", "description, followersCount"] for basic info, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "minLength": 1,
      "description": "User ID (numeric) or username depending on identifierType."
    },
    "identifierType": {
      "type": "string",
      "enum": [
        "id",
        "username"
      ],
      "description": "Type of identifier provided. Use \"id\" for numeric user ID, \"username\" for username."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"name\"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"name\", \"description, followersCount\"] for basic info, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "identifier",
    "identifierType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

searchTwitterUsers

Search users by person name, partial username, or fuzzy match using real-time external API. PRIMARY USE: When given person's name (e.g., "Elon Musk", "Sam Altman"), partial info, or uncertain username. Use for: Name-based search, finding multiple candidates, fuzzy matching, discovering users. NOT for: Exact username lookup (use getTwitterUserByUsername when username is certain). Optional fields parameter for performance (default: ["id", "username", "name"]). Available fields: id, username, name, description, location, followersCount, followingCount, verified, profileImageUrl, and more. Returns: array of matching users (default 10, max 10) with id, username, name, bio, followers_count. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

name	string	required
limit	number	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "name"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: ["id", "username"] for minimal, ["username", "name", "description, followersCount"] for basic info, or specify all fields if needed.
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "type": "number",
      "minimum": 1
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"name\"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"name\", \"description, followersCount\"] for basic info, or specify all fields if needed."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterUserConnections

Get Twitter user connections (followers or following). Use connectionType="followers" for users who follow them, connectionType="following" for users they follow. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. PAGING (responseType="paging"): Async paginated results (1000/page with default fields, 100/page with extra fields), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: network analysis, audience demographics, engagement patterns. Optional fields parameter for performance (default: ["id", "username", "name"]). Available fields: id, username, name, description, location, followersCount, followingCount, verified, profileImageUrl, and more. DATA FRESHNESS: Automatically checks data age (> 1 week triggers refresh from API). FORCE LATEST: Use sparingly - forceLatest=true bypasses cache for real-time data (increases latency/costs). CRITICAL - Understanding totalRows vs totalDataCount: totalRows indicates ONLY what we have in our database. totalDataCount (when present) shows the actual count from Twitter. If totalDataCount is missing or undefined, you CANNOT claim totalRows represents all connections - it only shows our partial database data. If totalDataCount > totalRows, we only have partial data. Always check if totalDataCount exists before making claims about total counts. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters14

username	string	required	Twitter username (without @ symbol).
connectionType	string	required	Type of connection to retrieve. Use "followers" for users who follow this account, "following" for users this account follows.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "name"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: ["id", "username"] for minimal, ["username", "name", "description, followersCount"] for basic info, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 1,
      "pattern": "^@?[a-zA-Z0-9_]{1,15}$",
      "description": "Twitter username (without @ symbol)."
    },
    "connectionType": {
      "type": "string",
      "enum": [
        "followers",
        "following"
      ],
      "description": "Type of connection to retrieve. Use \"followers\" for users who follow this account, \"following\" for users this account follows."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"name\"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"name\", \"description, followersCount\"] for basic info, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "username",
    "connectionType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterUsersByKeywords

Search for USERS who authored tweets/comments/quotes/retweets matching keywords. USE CASE: Find users who have posted content about specific topics, keywords, or phrases. Returns unique, deduplicated user profiles. RESPONSE MODES (responseType parameter): "fast" (DEFAULT): Returns up to 300 results directly in one call. Use limit param to reduce. Best for quick lookups. "paging": Async paginated results (100/page). Returns operation ID - call checkOperationStatus to get results. Use pageNumber/tableName for subsequent pages. "csv": Async CSV export. Returns dataDumpExportOperationId - call checkOperationStatus to get S3 download link. Best for bulk export. PAGING MODE DETAILS: FIRST CALL: Omit pageNumber and tableName. Creates cached table, returns page 1 with pagination metadata (tableName, totalPages, totalRows). SUBSEQUENT PAGES: Use tableName from first response with pageNumber (2, 3, etc.). BULK FETCH: Use pageNumberEnd with pageNumber and tableName for multiple consecutive pages. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). FILTERS: - startDate/endDate: Filter by tweet date (YYYY-MM-DD format). OMIT by default, only use if user explicitly requests date range. IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. - language: Filter tweets by language (en, EN, English, es, Spanish, etc.). Optional fields parameter for performance (default: ["id", "username", "name"]). Available fields: id, username, name, description, location, followersCount, followingCount, verified, profileImageUrl, and more. AGGREGATE FIELDS (from matching tweets) - MUST BE EXPLICITLY REQUESTED IN FIELDS: aggRelevance (relevance score for sorting), relevantTweetsCount (count of matching tweets per user), relevantTweetsImpressionsSum, relevantTweetsLikesSum, relevantTweetsQuotesSum, relevantTweetsRepliesSum, relevantTweetsRetweetsSum. These return aggregated metrics from all matched tweets for each user. Returns: results array of unique user profiles, count. In paging mode: pagination object, dataDumpExportOperationId for CSV. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters16

query	string	required	Full-text search of tweet content to find users who authored matching posts. Searches tweets/comments/quotes/retweets, returns UNIQUE user authors (deduplicated). EXACT PHRASES: Wrap in double quotes - "machine learning" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - AI robotics blockchain. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use "deep learning" AND python (not "deep learning python"). Use tensorflow OR pytorch (not "tensorflow pytorch"). PARENTHESES: Group terms for precise logic - (AI OR "artificial intelligence") AND ethics. FORBIDDEN: DO NOT use filter operators with colons (from:, to:, lang:, since:, until:) - use dedicated parameters instead. Query examples: "climate change" \| AI OR blockchain \| "neural networks" AND python \| (startup OR entrepreneur) NOT "venture capital"
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
language	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "name"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. Aggregations (from matching tweets, not all tweets of the user): aggRelevance (relevance score), relevantTweetsCount (count of matching tweets), relevantTweetsImpressionsSum, relevantTweetsLikesSum, relevantTweetsQuotesSum, relevantTweetsRepliesSum, relevantTweetsRetweetsSum. EXAMPLES: ["id", "username"] for minimal, ["username", "name", "followersCount", "relevantTweetsLikesSum", "relevantTweetsCount"] to include engagement aggregations.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Full-text search of tweet content to find users who authored matching posts. Searches tweets/comments/quotes/retweets, returns UNIQUE user authors (deduplicated). EXACT PHRASES: Wrap in double quotes - \"machine learning\" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - AI robotics blockchain. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use \"deep learning\" AND python (not \"deep learning python\"). Use tensorflow OR pytorch (not \"tensorflow pytorch\"). PARENTHESES: Group terms for precise logic - (AI OR \"artificial intelligence\") AND ethics. FORBIDDEN: DO NOT use filter operators with colons (from:, to:, lang:, since:, until:) - use dedicated parameters instead. Query examples: \"climate change\" | AI OR blockchain | \"neural networks\" AND python | (startup OR entrepreneur) NOT \"venture capital\""
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"name\"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. Aggregations (from matching tweets, not all tweets of the user): aggRelevance (relevance score), relevantTweetsCount (count of matching tweets), relevantTweetsImpressionsSum, relevantTweetsLikesSum, relevantTweetsQuotesSum, relevantTweetsRepliesSum, relevantTweetsRetweetsSum. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"name\", \"followersCount\", \"relevantTweetsLikesSum\", \"relevantTweetsCount\"] to include engagement aggregations."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterPostsByIds

Get multiple Twitter posts by numeric IDs (1-100 IDs per request). Returns results directly. Returns only found tweets, omitting not-found IDs for flexibility. First searches database, then external API for missing/stale data in parallel. Use when you have multiple exact post IDs. NOT for search - use getTwitterPostsByKeywords. PERFORMANCE: Much more efficient than multiple single-ID calls. Batches database queries and parallelizes API calls. Optional fields parameter for performance: ["id", "text", "retweetCount"]. Returns: results array with id, text, authorId, createdAt, metrics (retweets, replies, quotes), count, dataSource. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

postIds	array	required	Array of numeric Twitter post IDs (1-100 IDs). Examples: ["1849537602858893568", "1849012345678901234"]. Returns only found tweets, omitting not-found IDs.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "text", "authorUsername", "createdAtDate"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: ["id", "text"] for minimal, ["id", "text", "retweetCount", "likeCount", "hashtags"] for basic analysis, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postIds": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\d+$"
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Array of numeric Twitter post IDs (1-100 IDs). Examples: [\"1849537602858893568\", \"1849012345678901234\"]. Returns only found tweets, omitting not-found IDs."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"text\", \"authorUsername\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: [\"id\", \"text\"] for minimal, [\"id\", \"text\", \"retweetCount\", \"likeCount\", \"hashtags\"] for basic analysis, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postIds"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterPostsByAuthor

Get posts from author by username with multiple response modes. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: statistical analysis, trend detection, data visualization, processing thousands of posts. Returns by default: id, text, authorUsername, createdAtDate. First searches database, then external API if data is stale or missing. Date filters: OMIT startDate/endDate parameters by default to retrieve all posts. ONLY pass these if user explicitly requests specific date range (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FIELDS parameter (optional): Specify to get additional/different fields. Available: Core (id, text, authorId, authorUsername, createdAt), Engagement (retweetCount, replyCount, quoteCount, impressionCount, bookmarkCount), Metadata (lang, source, suspended, deleted), Relations (conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername), Content (hashtags, mentions, mediaUrls), Location (country, region, city). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

username	string	required	Twitter username (handle) of the author. Example: "elonmusk".
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "text", "authorUsername", "createdAtDate"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: ["id", "text"] for minimal, ["id", "text", "retweetCount", "likeCount", "hashtags"] for basic analysis, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 1,
      "description": "Twitter username (handle) of the author. Example: \"elonmusk\"."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"text\", \"authorUsername\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: [\"id\", \"text\"] for minimal, [\"id\", \"text\", \"retweetCount\", \"likeCount\", \"hashtags\"] for basic analysis, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "username"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterPostsByKeywords

Search posts by keywords. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: sentiment analysis, trend detection, content analysis across thousands of posts. Returns by default: id, text, authorUsername, createdAtDate. First searches database, then external API if data is stale or missing. NOT for URL lookups - use getTwitterPostsByIds. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). Filters: language, authorId/authorUsername. Date filters: OMIT startDate/endDate by default. ONLY pass if user explicitly requests specific date range (YYYY-MM-DD format). Use filterOutRetweets=true to exclude retweets. IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FIELDS parameter (optional): Specify to get additional/different fields. Available: Core (id, text, authorId, authorUsername, createdAt), Engagement (retweetCount, replyCount, quoteCount, impressionCount, bookmarkCount), Metadata (lang, source, suspended, deleted), Relations (conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername), Content (hashtags, mentions, mediaUrls), Location (country, region, city). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters19

query	string	required	Full-text search of post content ONLY. Searches the text/content of posts, NOT author information. EXACT PHRASES: Wrap in double quotes - "machine learning" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - AI robotics blockchain. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use "deep learning" AND python (not "deep learning python"). Use tensorflow OR pytorch (not "tensorflow pytorch"). PARENTHESES: Group terms for precise logic - (AI OR "artificial intelligence") AND ethics. FORBIDDEN: NEVER use from:username or author filters in this parameter. Use the authorUsername parameter instead. FORBIDDEN: DO NOT use filter operators with colons (from:, to:, lang:, since:, until:) - use dedicated parameters instead. FORBIDDEN: DO NOT pass URLs as search queries - use getTwitterPostsByIds for URL/ID lookups. Query examples: "climate change" \| AI OR blockchain \| "neural networks" AND python \| (startup OR entrepreneur) NOT "venture capital"
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
authorUsername	string	optional	Filter posts by author username. Use this parameter to search posts from a specific user. Example: authorUsername="elonmusk" finds all posts by @elonmusk. NEVER use from:username in query - always use this parameter instead.
authorId	string	optional	Filter posts by author ID (numeric string). Alternative to authorUsername.
language	string	optional
filterOutRetweets	boolean	optional	Exclude retweets from results. When true, only original posts are returned. Default: false (include retweets).
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "text", "authorUsername", "createdAtDate"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: ["id", "text"] for minimal, ["id", "text", "retweetCount", "likeCount", "hashtags"] for basic analysis, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Full-text search of post content ONLY. Searches the text/content of posts, NOT author information. EXACT PHRASES: Wrap in double quotes - \"machine learning\" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - AI robotics blockchain. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use \"deep learning\" AND python (not \"deep learning python\"). Use tensorflow OR pytorch (not \"tensorflow pytorch\"). PARENTHESES: Group terms for precise logic - (AI OR \"artificial intelligence\") AND ethics. FORBIDDEN: NEVER use from:username or author filters in this parameter. Use the authorUsername parameter instead. FORBIDDEN: DO NOT use filter operators with colons (from:, to:, lang:, since:, until:) - use dedicated parameters instead. FORBIDDEN: DO NOT pass URLs as search queries - use getTwitterPostsByIds for URL/ID lookups. Query examples: \"climate change\" | AI OR blockchain | \"neural networks\" AND python | (startup OR entrepreneur) NOT \"venture capital\""
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "authorUsername": {
      "type": "string",
      "description": "Filter posts by author username. Use this parameter to search posts from a specific user. Example: authorUsername=\"elonmusk\" finds all posts by @elonmusk. NEVER use from:username in query - always use this parameter instead."
    },
    "authorId": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "Filter posts by author ID (numeric string). Alternative to authorUsername."
    },
    "language": {
      "type": "string"
    },
    "filterOutRetweets": {
      "type": "boolean",
      "default": false,
      "description": "Exclude retweets from results. When true, only original posts are returned. Default: false (include retweets)."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"text\", \"authorUsername\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: [\"id\", \"text\"] for minimal, [\"id\", \"text\", \"retweetCount\", \"likeCount\", \"hashtags\"] for basic analysis, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterPostRetweets

Get retweets of specific post. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Database-only. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. Database-only search for historical retweet data. Date filter: OMIT startDate by default. ONLY pass if user explicitly requests filtering from specific date (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Use to analyze post amplification patterns. NOT for quotes - use getTwitterPostQuotes. Optional fields parameter for performance: ["id", "authorUsername", "createdAt"]. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters14

postId	string	required	Numeric Twitter post/tweet ID. Must be a number-only string (e.g., "1234567890"). Do NOT pass tweet text, URLs, or usernames here.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "text", "authorUsername", "createdAtDate"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: ["id", "text"] for minimal, ["id", "text", "retweetCount", "likeCount", "hashtags"] for basic analysis, or specify all fields if needed.
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "Numeric Twitter post/tweet ID. Must be a number-only string (e.g., \"1234567890\"). Do NOT pass tweet text, URLs, or usernames here."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"text\", \"authorUsername\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: [\"id\", \"text\"] for minimal, [\"id\", \"text\", \"retweetCount\", \"likeCount\", \"hashtags\"] for basic analysis, or specify all fields if needed."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterPostQuotes

Get quote posts of specific post. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze all quote tweets. Ideal for: sentiment analysis on reactions, commentary patterns, viral spread analysis. First searches database, then external API if data is stale (>10 days). Date filter: OMIT startDate by default. ONLY pass if user explicitly requests filtering from specific date (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Use to analyze commentary on post. NOT for retweets - use getTwitterPostRetweets. Optional fields parameter for performance: ["id", "text", "authorUsername", "createdAt"]. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters14

postId	string	required	Numeric Twitter post/tweet ID. Must be a number-only string (e.g., "1234567890"). Do NOT pass tweet text, URLs, or usernames here.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "text", "authorUsername", "createdAtDate"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: ["id", "text"] for minimal, ["id", "text", "retweetCount", "likeCount", "hashtags"] for basic analysis, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "Numeric Twitter post/tweet ID. Must be a number-only string (e.g., \"1234567890\"). Do NOT pass tweet text, URLs, or usernames here."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"text\", \"authorUsername\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: [\"id\", \"text\"] for minimal, [\"id\", \"text\", \"retweetCount\", \"likeCount\", \"hashtags\"] for basic analysis, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterPostComments

Get comments (replies) to specific post. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze all comments. Ideal for: sentiment analysis, discussion themes, community engagement analysis. First searches database, then external API if data is stale (>10 days). Date filter: OMIT startDate by default. ONLY pass if user explicitly requests filtering from specific date (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Use to analyze community response and discussion. NOT for quotes - use getTwitterPostQuotes. Optional fields parameter for performance: ["id", "text", "authorUsername", "createdAt"]. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters14

postId	string	required	Numeric Twitter post/tweet ID. Must be a number-only string (e.g., "1234567890"). Do NOT pass tweet text, URLs, or usernames here.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "text", "authorUsername", "createdAtDate"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: ["id", "text"] for minimal, ["id", "text", "retweetCount", "likeCount", "hashtags"] for basic analysis, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "Numeric Twitter post/tweet ID. Must be a number-only string (e.g., \"1234567890\"). Do NOT pass tweet text, URLs, or usernames here."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"text\", \"authorUsername\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, text, authorId, authorUsername, createdAt, createdAtDate. Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount. Metadata: lang, possiblySensitive, suspended, deleted, source, isRetweet, hasBirdwatchNotes, status. Birdwatch: birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl. Relations: conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId (original tweet ID if edited, equals own ID if unedited), editedTweets (array of edited version IDs). Content: hashtags, mentions, mediaUrls, urls, grokGeneratedContent (array of Grok AI generated content grok_post_id, grok_url, media_id). Location: country, region, city. EXAMPLES: [\"id\", \"text\"] for minimal, [\"id\", \"text\", \"retweetCount\", \"likeCount\", \"hashtags\"] for basic analysis, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

countTweets

Count tweets containing a specific phrase within a date range. Returns the total count of matching tweets (int) directly, or zero if none found. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). Filters: date range (startDate/endDate in YYYY-MM-DD). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Default: startDate=6 months ago if not provided. Use for analytics and trend analysis without retrieving full tweet data. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

phrase	string	required	Count only tweets containing the phrase
startDate	string	optional	Start date in YYYY-MM-DD format. Default: 6 months ago
endDate	string	optional	End date in YYYY-MM-DD format. Default: current date
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "phrase": {
      "type": "string",
      "minLength": 1,
      "description": "Count only tweets containing the phrase"
    },
    "startDate": {
      "type": "string",
      "description": "Start date in YYYY-MM-DD format. Default: 6 months ago"
    },
    "endDate": {
      "type": "string",
      "description": "End date in YYYY-MM-DD format. Default: current date"
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "phrase"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTwitterPostInteractingUsers

Get users who interacted with a specific Twitter post (commenters, quoters, or retweeters). INTERACTION TYPES: "commenters" (users who replied to the post), "quoters" (users who quoted the post), "retweeters" (users who retweeted the post). FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback when DB data is stale or insufficient. Results include guidance for paging mode. PAGING (responseType="paging"): Async paginated results (1000/page with default fields, 100/page if extra fields). Returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: audience analysis, engagement patterns, network graphs across thousands of users. PAGING MODE DETAILS: FIRST CALL: Omit pageNumber and tableName. Creates cached table, returns page 1 with pagination metadata (tableName, totalPages, totalRows). SUBSEQUENT PAGES: Use tableName from first response with pageNumber (2, 3, etc.) to fetch additional pages. Cannot pass pageNumber without tableName. BULK FETCH: Optionally use pageNumberEnd with pageNumber and tableName to fetch multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 returns pages 1-5). Optional fields parameter for performance (default: ["id", "username", "name"]). Available fields: id, username, name, description, location, followersCount, followingCount, verified, profileImageUrl, and more. DATA FRESHNESS: Automatically checks data age (> 1 week triggers refresh from API). FORCE LATEST: Use sparingly - forceLatest=true bypasses cache for real-time data (increases latency/costs). Use for: Finding who engaged with a specific post, analyzing post reach and audience, building engagement networks. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters16

postId	string	required	Numeric Twitter post/tweet ID. Must be a number-only string (e.g., "1234567890"). Do NOT pass tweet text, URLs, or usernames here.
interactionType	string	required	Type of interaction to retrieve users for. Options: "commenters" (users who replied), "quoters" (users who quoted), "retweeters" (users who retweeted). Each type queries different relationships in the data.
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
startDate	string	optional
endDate	string	optional
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "name"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: ["id", "username"] for minimal, ["username", "name", "description, followersCount"] for basic info, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "Numeric Twitter post/tweet ID. Must be a number-only string (e.g., \"1234567890\"). Do NOT pass tweet text, URLs, or usernames here."
    },
    "interactionType": {
      "type": "string",
      "enum": [
        "commenters",
        "quoters",
        "retweeters"
      ],
      "description": "Type of interaction to retrieve users for. Options: \"commenters\" (users who replied), \"quoters\" (users who quoted), \"retweeters\" (users who retweeted). Each type queries different relationships in the data."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"name\"]. AVAILABLE FIELDS: Core: id, username, name, description, location, verified, verifiedType, protected. Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount. Profile: profileImageUrl, profileBannerUrl, profileInterstitialType. Metadata: source, status, pinnedTweetId, isVerified, accountBasedIn, locationAccurate, label, labelType. Advanced: nLang, nLangsFiltered. Timestamps: modifiedAt, createdAt. Account History: verifiedSinceDatetime, usernameChanges, lastUsernameChangeDatetime. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"name\", \"description, followersCount\"] for basic info, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postId",
    "interactionType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

checkOperationStatus

checkOperationStatus: poll an async operation and retrieve its results or CSV download URL. Use this after any tool call made with responseType="paging" or responseType="csv" — those return an operationId that must be polled via checkOperationStatus to get the actual data. Also handles background job status checks, presigned S3 link retrieval for data dumps, and completion polling for long-running queries. Required: operationId. HANDLES TWO TYPES: (1) Query operations (op_toolname_xxx): returns paginated results + dataDumpExportOperationId. (2) Export operations (op_datadump_xxx): returns download URL for CSV download. CRITICAL: You MUST keep polling until operation finishes. DO NOT stop until status is success/no_data/error/cancelled. POLLING LOOP: (1) Call immediately after getting operation ID. (2) If status=running, wait exactly 5 seconds. (3) Call again after 5 seconds. (4) Repeat step 2-3 continuously until status changes to success/no_data/error/cancelled. (5) Only stop when operation is finished. NOTE: status values returned are wire-level ResponseStatus (success/no_data/error/running/cancelled). Returns: For queries - results, pagination, dataDumpExportOperationId. For exports - downloadUrl, fileName, totalRows. NEVER make calls without 5 second waits between them. MIGRATION NOTE: checkOperationStatus was renamed from checkDataDumpOperationStatus and getOperationResults — if you were calling those tool names, use this one instead.

Parameters3

operationId	string	required	The operation ID
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "operationId": {
      "type": "string",
      "description": "The operation ID"
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    }
  },
  "required": [
    "operationId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

cancelOperation

Cancel running operation. Required: operationId. Gracefully stops operation at next checkpoint. Returns confirmation. Use checkOperationStatus to verify cancellation completed.

Parameters3

operationId	string	required	The operation ID
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "operationId": {
      "type": "string",
      "description": "The operation ID"
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    }
  },
  "required": [
    "operationId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getInstagramPostsByIds

Get multiple Instagram posts by IDs (1-100 IDs per request). Returns results directly. Returns only found posts, omitting not-found IDs for flexibility. First searches database, then external API for missing/stale data in parallel. Use when you have multiple exact post IDs. NOT for search - use getInstagramPostsByKeywords. PERFORMANCE: Much more efficient than multiple single-ID calls. Batches database queries and parallelizes API calls. IMPORTANT: postIds must be in strong_id format (e.g., "3606450040306139062_4836333238") - use the full "id" value from other Instagram tools, NOT just the media_id. To find a post from an Instagram URL (e.g., instagram.com/p/ABC123/), extract the shortcode from the URL path and use getInstagramPostsByKeywords to search, or ask the user for the post ID. Optional fields parameter for performance: ["id", "caption", "likeCount"]. Returns: results array with id, caption, userId, username, createdAtDate, engagement metrics, count, dataSource. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

postIds	array	required	Array of Instagram post IDs to fetch (1-100 IDs). Returns only found posts, omitting not-found IDs. REQUIRED FORMAT: strong_id (e.g., "3606450040306139062_4836333238"). This is the complete post identifier consisting of media_id + underscore + user_id. When receiving the post id from other instagram tools, use the full "id" value. DO NOT use only the media_id portion.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "caption", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, postType, userId, username, fullName, caption, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount, commentCount, reshareCount, videoPlayCount. Media: mediaType, codeUrl, imageUrl, videoUrl, audioOnlyUrl, profilePicUrl, videoSubtitlesUri, subtitles, videoDuration. EXAMPLES: ["id", "caption"] for minimal, ["id", "caption", "username", "createdAtDate", "likeCount"] for basic analysis, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postIds": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\d+_\\d+$"
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Array of Instagram post IDs to fetch (1-100 IDs). Returns only found posts, omitting not-found IDs. REQUIRED FORMAT: strong_id (e.g., \"3606450040306139062_4836333238\"). This is the complete post identifier consisting of media_id + underscore + user_id. When receiving the post id from other instagram tools, use the full \"id\" value. DO NOT use only the media_id portion."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"caption\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, postType, userId, username, fullName, caption, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount, commentCount, reshareCount, videoPlayCount. Media: mediaType, codeUrl, imageUrl, videoUrl, audioOnlyUrl, profilePicUrl, videoSubtitlesUri, subtitles, videoDuration. EXAMPLES: [\"id\", \"caption\"] for minimal, [\"id\", \"caption\", \"username\", \"createdAtDate\", \"likeCount\"] for basic analysis, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postIds"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getInstagramPostsByUser

Get posts from Instagram user by ID or username with two response modes. Use identifierType="id" for numeric user ID, identifierType="username" for username. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: engagement analysis, content trends, posting patterns across all posts. Returns by default: id, caption, username, createdAtDate. Date filters: OMIT startDate/endDate parameters by default to retrieve all posts. ONLY pass these if user explicitly requests specific date range (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FIELDS parameter (optional): Specify to get additional/different fields. Available: Core (id, caption, userId, username, fullName, createdAtDate), Engagement (likeCount, commentCount, reshareCount, videoPlayCount), Media (mediaType, imageUrl, videoUrl, subtitles, videoDuration). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters16

identifier	string	required	User ID (numeric) or username depending on identifierType.
identifierType	string	required	Type of identifier provided. Use "id" for numeric user ID, "username" for username.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "caption", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, postType, userId, username, fullName, caption, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount, commentCount, reshareCount, videoPlayCount. Media: mediaType, codeUrl, imageUrl, videoUrl, audioOnlyUrl, profilePicUrl, videoSubtitlesUri, subtitles, videoDuration. EXAMPLES: ["id", "caption"] for minimal, ["id", "caption", "username", "createdAtDate", "likeCount"] for basic analysis, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "minLength": 1,
      "description": "User ID (numeric) or username depending on identifierType."
    },
    "identifierType": {
      "type": "string",
      "enum": [
        "id",
        "username"
      ],
      "description": "Type of identifier provided. Use \"id\" for numeric user ID, \"username\" for username."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"caption\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, postType, userId, username, fullName, caption, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount, commentCount, reshareCount, videoPlayCount. Media: mediaType, codeUrl, imageUrl, videoUrl, audioOnlyUrl, profilePicUrl, videoSubtitlesUri, subtitles, videoDuration. EXAMPLES: [\"id\", \"caption\"] for minimal, [\"id\", \"caption\", \"username\", \"createdAtDate\", \"likeCount\"] for basic analysis, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "identifier",
    "identifierType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getInstagramPostsByKeywords

Search Instagram posts by keywords with two response modes. Searches in both post captions and video subtitles. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: content analysis, hashtag trends, brand monitoring across thousands of posts. Returns by default: id, caption, username, createdAtDate. First searches database, then external API if data is stale or missing. NOT for URL lookups or post ID lookups - use getInstagramPostsByIds instead. Query must be plain text keywords/phrases, not URLs or IDs. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). Date filters: OMIT startDate/endDate parameters by default. ONLY pass these if user explicitly requests specific date range (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FIELDS parameter (optional): Specify to get additional/different fields. Available: Core (id, caption, userId, username, fullName, createdAtDate), Engagement (likeCount, commentCount, reshareCount, videoPlayCount), Media (mediaType, imageUrl, videoUrl, subtitles, videoDuration). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

query	string	required	Plain text keywords or phrases to search in post captions and subtitles. Use double quotes for exact phrases. Do NOT pass URLs, post IDs, or special syntax - only search terms. Examples: "travel photography", food OR cooking, "sunset beach" AND california
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "caption", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, postType, userId, username, fullName, caption, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount, commentCount, reshareCount, videoPlayCount. Media: mediaType, codeUrl, imageUrl, videoUrl, audioOnlyUrl, profilePicUrl, videoSubtitlesUri, subtitles, videoDuration. EXAMPLES: ["id", "caption"] for minimal, ["id", "caption", "username", "createdAtDate", "likeCount"] for basic analysis, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Plain text keywords or phrases to search in post captions and subtitles. Use double quotes for exact phrases. Do NOT pass URLs, post IDs, or special syntax - only search terms. Examples: \"travel photography\", food OR cooking, \"sunset beach\" AND california"
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"caption\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, postType, userId, username, fullName, caption, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount, commentCount, reshareCount, videoPlayCount. Media: mediaType, codeUrl, imageUrl, videoUrl, audioOnlyUrl, profilePicUrl, videoSubtitlesUri, subtitles, videoDuration. EXAMPLES: [\"id\", \"caption\"] for minimal, [\"id\", \"caption\", \"username\", \"createdAtDate\", \"likeCount\"] for basic analysis, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getInstagramUser

Get Instagram user profile by ID or username. Use identifierType="id" for numeric user ID, identifierType="username" for username. For username: Use ONLY when you have the precise username (e.g., "cristiano"). For person names or fuzzy search, use searchInstagramUsers instead. Optional fields parameter for performance (default: ["id", "username", "fullName"]). Available fields: id, username, fullName, biography, isPrivate, isVerified, followerCount, followingCount, mediaCount, profilePicUrl, and more. Returns: single user profile with userId, username, fullName, followerCount, followingCount, mediaCount, biography, isVerified, isPrivate, profilePicUrl. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters9

identifier	string	required	User ID (numeric) or username depending on identifierType.
identifierType	string	required	Type of identifier provided. Use "id" for numeric user ID, "username" for username.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "fullName"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. EXAMPLES: ["id", "username"] for minimal, ["username", "fullName", "followerCount"] for basic info, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "minLength": 1,
      "description": "User ID (numeric) or username depending on identifierType."
    },
    "identifierType": {
      "type": "string",
      "enum": [
        "id",
        "username"
      ],
      "description": "Type of identifier provided. Use \"id\" for numeric user ID, \"username\" for username."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"fullName\"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"fullName\", \"followerCount\"] for basic info, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "identifier",
    "identifierType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

searchInstagramUsers

Search users by person name, partial username, or fuzzy match using real-time external API. PRIMARY USE: When given person's name (e.g., "Cristiano Ronaldo", "Kim Kardashian"), partial info, or uncertain username. Use for: Name-based search, finding multiple candidates, fuzzy matching, discovering users. NOT for: Exact username lookup (use getInstagramUserByUsername when username is certain). Optional fields parameter for performance (default: ["id", "username", "fullName"]). Available fields: id, username, fullName, biography, isPrivate, isVerified, followerCount, followingCount, mediaCount, profilePicUrl, and more. Returns: array of matching users (default 10, max 10) with userId, username, fullName, followerCount, biography, profilePicUrl. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

name	string	required	Search query for Instagram users. Supports partial name or username matching.
limit	number	optional	Maximum number of users to return. Default: 10, Max: 10.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "fullName"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. EXAMPLES: ["id", "username"] for minimal, ["username", "fullName", "followerCount"] for basic info, or specify all fields if needed.
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Search query for Instagram users. Supports partial name or username matching."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 10,
      "description": "Maximum number of users to return. Default: 10, Max: 10."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"fullName\"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"fullName\", \"followerCount\"] for basic info, or specify all fields if needed."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getInstagramUserConnections

Get Instagram user connections (followers or following). Use connectionType="followers" for users who follow them, connectionType="following" for users they follow. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. PAGING (responseType="paging"): Async paginated results (100 users per page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. Optional fields parameter for performance (default: ["id", "username", "fullName"]). Available fields: id, username, fullName, biography, isPrivate, isVerified, followerCount, followingCount, mediaCount, profilePicUrl, and more. DATA FRESHNESS: Automatically checks data age (> 1 week triggers refresh from API). FORCE LATEST: Use sparingly - forceLatest=true bypasses cache for real-time data (increases latency/costs). CRITICAL - Understanding totalRows vs totalDataCount: totalRows indicates ONLY what we have in our database. totalDataCount (when present) shows the actual count from Instagram. If totalDataCount is missing or undefined, you CANNOT claim totalRows represents all connections - it only shows our partial database data. If totalDataCount > totalRows, we only have partial data. Always check if totalDataCount exists before making claims about total counts. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters14

username	string	required	Instagram username (without @ symbol)
connectionType	string	required	Type of connection to retrieve. Use "followers" for users who follow this account, "following" for users this account follows.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "fullName"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. EXAMPLES: ["id", "username"] for minimal, ["username", "fullName", "followerCount"] for basic info, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 1,
      "pattern": "^@?[a-zA-Z0-9._]{1,30}$",
      "description": "Instagram username (without @ symbol)"
    },
    "connectionType": {
      "type": "string",
      "enum": [
        "followers",
        "following"
      ],
      "description": "Type of connection to retrieve. Use \"followers\" for users who follow this account, \"following\" for users this account follows."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"fullName\"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"fullName\", \"followerCount\"] for basic info, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "username",
    "connectionType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getInstagramPostInteractingUsers

Get USER PROFILES of people who interacted with an Instagram post. Returns full user data (bio, followerCount, followingCount, etc.). RETURNS USER PROFILES: id, username, fullName, biography, followerCount, followingCount, isVerified, profilePicUrl. Use for analyzing WHO engaged with a post. NOT FOR COMMENT TEXT: To read the actual comment content (what people wrote), use getInstagramCommentsByPostId instead. INTERACTION TYPES: "commenters" (users who commented), "likers" (users who liked). WHEN TO USE THIS TOOL: Analyzing commenters/likers demographics, finding influencers who engaged, building audience profiles, network analysis of who interacts with posts. WHEN TO USE getInstagramCommentsByPostId: Reading comment text, sentiment analysis of what was said, analyzing discussion content. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for commenters when stale. PAGING (responseType="paging"): Async paginated results (1000 users per page with default fields), returns operationId - IMMEDIATELY call checkOperationStatus to get results. CSV export included via dataDumpExportOperationId. Supports pageNumber/tableName for subsequent pages. Optional fields (default: ["id", "username", "fullName"]). Available: biography, isPrivate, isVerified, followerCount, followingCount, mediaCount, profilePicUrl. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters14

postId	string	required	REQUIRED FORMAT: strong_id (e.g., "3606450040306139062_4836333238"). This is the complete post identifier consisting of media_id + underscore + user_id. When receiving the post id from other instagram tools, use the full "id" valueDO NOT use only the media_id portion.
interactionType	string	required	Type of interaction to retrieve users for. Options: "commenters" (users who commented on the post), "likers" (users who liked the post). Each type queries different relationships in the data.
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "fullName"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. EXAMPLES: ["id", "username"] for minimal, ["username", "fullName", "followerCount"] for basic info, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "pattern": "^\\d+_\\d+$",
      "description": "REQUIRED FORMAT: strong_id (e.g., \"3606450040306139062_4836333238\"). This is the complete post identifier consisting of media_id + underscore + user_id. When receiving the post id from other instagram tools, use the full \"id\" valueDO NOT use only the media_id portion."
    },
    "interactionType": {
      "type": "string",
      "enum": [
        "commenters",
        "likers"
      ],
      "description": "Type of interaction to retrieve users for. Options: \"commenters\" (users who commented on the post), \"likers\" (users who liked the post). Each type queries different relationships in the data."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"fullName\"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"fullName\", \"followerCount\"] for basic info, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postId",
    "interactionType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getInstagramUsersByKeywords

Search for USERS who authored Instagram posts matching keywords. USE CASE: Find users who have posted content about specific topics, keywords, or phrases. Returns unique, deduplicated user profiles. RESPONSE MODES (responseType parameter): "fast" (DEFAULT): Returns up to 300 results directly in one call. Use limit param to reduce. Best for quick lookups. "paging": Async paginated results (100/page). Returns operation ID - call checkOperationStatus to get results. Use pageNumber/tableName for subsequent pages. "csv": Async CSV export. Returns dataDumpExportOperationId - call checkOperationStatus to get S3 download link. Best for bulk export. PAGING MODE DETAILS: FIRST CALL: Omit pageNumber and tableName. Creates cached table, returns page 1 with pagination metadata (tableName, totalPages, totalRows). SUBSEQUENT PAGES: Use tableName from first response with pageNumber (2, 3, etc.). BULK FETCH: Use pageNumberEnd with pageNumber and tableName for multiple consecutive pages. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). FILTERS: - startDate/endDate: Filter by post date (YYYY-MM-DD format). OMIT by default, only use if user explicitly requests date range. IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Optional fields parameter for performance (default: ["id", "username", "fullName"]). Available fields: id, username, fullName, biography, isPrivate, isVerified, followerCount, followingCount, mediaCount, profilePicUrl, and more. AGGREGATE FIELDS (from matching posts) - MUST BE EXPLICITLY REQUESTED IN FIELDS: aggRelevance (relevance score for sorting), relevantPostsCount (count of matching posts per user), relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsResharesSum, relevantPostsVideoPlaysSum. These return aggregated metrics from all matched posts for each user. Returns: results array of unique user profiles, count. In paging mode: pagination object, dataDumpExportOperationId for CSV. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

query	string	required	Full-text search of Instagram post captions to find users who authored matching posts. Searches posts, returns UNIQUE user authors (deduplicated). EXACT PHRASES: Wrap in double quotes - "sustainable fashion" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - travel food photography. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use "travel photography" AND nature (not "travel photography nature"). Use fashion OR style (not "fashion style"). PARENTHESES: Group terms for precise logic - (travel OR adventure) AND ("sustainable living" NOT luxury). FORBIDDEN: DO NOT use filter operators with colons (from:, to:, since:, until:) - use dedicated parameters instead. Query examples: "climate change" \| fashion OR beauty \| "digital nomad" AND remote \| (startup OR entrepreneur) NOT "venture capital"
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "fullName"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. Aggregations (from matching posts, not all posts of the user): aggRelevance (relevance score), relevantPostsCount (count of matching posts), relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsResharesSum, relevantPostsVideoPlaysSum. EXAMPLES: ["id", "username"] for minimal, ["username", "fullName", "followerCount", "relevantPostsLikesSum", "relevantPostsCount"] to include engagement aggregations.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Full-text search of Instagram post captions to find users who authored matching posts. Searches posts, returns UNIQUE user authors (deduplicated). EXACT PHRASES: Wrap in double quotes - \"sustainable fashion\" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - travel food photography. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use \"travel photography\" AND nature (not \"travel photography nature\"). Use fashion OR style (not \"fashion style\"). PARENTHESES: Group terms for precise logic - (travel OR adventure) AND (\"sustainable living\" NOT luxury). FORBIDDEN: DO NOT use filter operators with colons (from:, to:, since:, until:) - use dedicated parameters instead. Query examples: \"climate change\" | fashion OR beauty | \"digital nomad\" AND remote | (startup OR entrepreneur) NOT \"venture capital\""
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"fullName\"]. AVAILABLE FIELDS: Core: id, username, fullName, biography, isPrivate, isVerified. Engagement: followerCount, followingCount, mediaCount. Profile: profilePicUrl, profilePicId, profileUrl, externalUrl, hasAnonymousProfilePicture. Aggregations (from matching posts, not all posts of the user): aggRelevance (relevance score), relevantPostsCount (count of matching posts), relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsResharesSum, relevantPostsVideoPlaysSum. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"fullName\", \"followerCount\", \"relevantPostsLikesSum\", \"relevantPostsCount\"] to include engagement aggregations."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getInstagramCommentsByPostId

Get COMMENT CONTENT (text, likes) for an Instagram post. Returns the actual comment objects with text and metadata. RETURNS COMMENT DATA: id, text, username, createdAtDate, likeCount, childCommentCount. Use for reading what people said. NOT FOR USER PROFILES: To get detailed user profiles (bio, followerCount, followingCount) of commenters, use getInstagramPostInteractingUsers with interactionType="commenters" instead. IMPORTANT: postId must be in strong_id format (e.g., "3606450040306139062_4836333238") - use the full "id" value from other Instagram tools, NOT just the media_id. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: sentiment analysis, reading discussions, analyzing comment content, engagement patterns. Date filters: OMIT startDate/endDate parameters by default. ONLY pass these if user explicitly requests specific date range (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Optional fields: ["id", "text", "username", "createdAtDate", "likeCount"]. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

postId	string	required	REQUIRED FORMAT: strong_id (e.g., "3606450040306139062_4836333238"). This is the complete post identifier consisting of media_id + underscore + user_id. When receiving the post id from other instagram tools, use the full "id" valueDO NOT use only the media_id portion.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "text", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, text, parentPostId, type, parentCommentId, repliedToCommentId, childCommentCount, userId, username, fullName, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount. Status: status, isSpam, hasTranslation. EXAMPLES: ["id", "text"] for minimal, ["id", "text", "username", "createdAtDate", "likeCount"] for basic analysis, or specify all fields if needed.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "pattern": "^\\d+_\\d+$",
      "description": "REQUIRED FORMAT: strong_id (e.g., \"3606450040306139062_4836333238\"). This is the complete post identifier consisting of media_id + underscore + user_id. When receiving the post id from other instagram tools, use the full \"id\" valueDO NOT use only the media_id portion."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"text\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, text, parentPostId, type, parentCommentId, repliedToCommentId, childCommentCount, userId, username, fullName, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount. Status: status, isSpam, hasTranslation. EXAMPLES: [\"id\", \"text\"] for minimal, [\"id\", \"text\", \"username\", \"createdAtDate\", \"likeCount\"] for basic analysis, or specify all fields if needed."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getRedditUser

Get Reddit user profile by username. Returns user profile including karma breakdown (link, comment, total), account status (gold, mod, employee), and profile info. Use without u/ prefix (e.g., "spez" not "u/spez"). Optional fields parameter for performance (default: ["id", "username", "totalKarma"]). Available fields: id, username, profileUrl, profilePicUrl, snoovatarImg, linkKarma, commentKarma, totalKarma, awardeeKarma, awarderKarma, isGold, isMod, isEmployee, hasVerifiedEmail, isSuspended, verified, isBlocked, acceptFollowers, hasSubscribed, hideFromRobots, prefShowSnoovatar, profileDescription, profileBannerUrl, profileTitle, createdAt. Returns: single user profile with id, username, karma metrics, account flags, and profile details. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

username	string	required	Reddit username (without u/ prefix)
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "totalKarma"]. AVAILABLE FIELDS: Core: id, username, profileUrl, profilePicUrl, snoovatarImg. Karma: linkKarma, commentKarma, totalKarma, awardeeKarma, awarderKarma. Status: isGold, isMod, isEmployee, hasVerifiedEmail, isSuspended, verified, isBlocked, acceptFollowers, hasSubscribed, hideFromRobots, prefShowSnoovatar. Profile: profileDescription, profileBannerUrl, profileTitle. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: ["id", "username"] for minimal, ["username", "totalKarma", "profileDescription"] for basic info.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 1,
      "description": "Reddit username (without u/ prefix)"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"totalKarma\"]. AVAILABLE FIELDS: Core: id, username, profileUrl, profilePicUrl, snoovatarImg. Karma: linkKarma, commentKarma, totalKarma, awardeeKarma, awarderKarma. Status: isGold, isMod, isEmployee, hasVerifiedEmail, isSuspended, verified, isBlocked, acceptFollowers, hasSubscribed, hideFromRobots, prefShowSnoovatar. Profile: profileDescription, profileBannerUrl, profileTitle. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"totalKarma\", \"profileDescription\"] for basic info."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "username"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

searchRedditUsers

Search Reddit users by name, username, or profile description using real-time external API. PRIMARY USE: When given a person's name (e.g., "spez", "GallowBoob"), partial info, or uncertain username. Use for: Name-based search, finding multiple candidates, fuzzy matching, discovering users. NOT for: Exact username lookup (use getRedditUser when username is certain). Optional fields parameter for performance (default: ["id", "username", "totalKarma"]). Available fields: id, username, profileUrl, profilePicUrl, snoovatarImg, linkKarma, commentKarma, totalKarma, awardeeKarma, awarderKarma, isGold, isMod, isEmployee, hasVerifiedEmail, isSuspended, verified, isBlocked, acceptFollowers, hasSubscribed, hideFromRobots, prefShowSnoovatar, profileDescription, profileBannerUrl, profileTitle, createdAt. Returns: array of matching users (default 50, max 50) with id, username, karma metrics, profile info. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

name	string	required	Search query for Reddit users. Can be username, name, or keywords from profile.
limit	integer	optional	Maximum number of users to return. Default: 50, Max: 50.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "totalKarma"]. AVAILABLE FIELDS: Core: id, username, profileUrl, profilePicUrl, snoovatarImg. Karma: linkKarma, commentKarma, totalKarma, awardeeKarma, awarderKarma. Status: isGold, isMod, isEmployee, hasVerifiedEmail, isSuspended, verified, isBlocked, acceptFollowers, hasSubscribed, hideFromRobots, prefShowSnoovatar. Profile: profileDescription, profileBannerUrl, profileTitle. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: ["id", "username"] for minimal, ["username", "totalKarma", "profileDescription"] for basic info.
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Search query for Reddit users. Can be username, name, or keywords from profile."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Maximum number of users to return. Default: 50, Max: 50."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"totalKarma\"]. AVAILABLE FIELDS: Core: id, username, profileUrl, profilePicUrl, snoovatarImg. Karma: linkKarma, commentKarma, totalKarma, awardeeKarma, awarderKarma. Status: isGold, isMod, isEmployee, hasVerifiedEmail, isSuspended, verified, isBlocked, acceptFollowers, hasSubscribed, hideFromRobots, prefShowSnoovatar. Profile: profileDescription, profileBannerUrl, profileTitle. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"totalKarma\", \"profileDescription\"] for basic info."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getRedditUsersByKeywords

Search for USERS who authored Reddit posts matching keywords. USE CASE: Find users who have posted content about specific topics. Returns unique, deduplicated user profiles. RESPONSE MODES (responseType parameter): "fast" (DEFAULT): Returns up to 300 results directly in one call. Use limit param to reduce. Best for quick lookups. "paging": Async paginated results (100/page). Returns operation ID - call checkOperationStatus to get results. Use pageNumber/tableName for subsequent pages. "csv": Async CSV export. Returns dataDumpExportOperationId - call checkOperationStatus to get S3 download link. Best for bulk export. PAGING MODE DETAILS: FIRST CALL: Omit pageNumber and tableName. Creates cached table, returns page 1 with pagination metadata (tableName, totalPages, totalRows). SUBSEQUENT PAGES: Use tableName from first response with pageNumber (2, 3, etc.). BULK FETCH: Use pageNumberEnd with pageNumber and tableName for multiple consecutive pages. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). FILTERS: - startDate/endDate: Filter by post date (YYYY-MM-DD format). OMIT by default, only use if user explicitly requests date range. IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. - subreddit: Filter to specific subreddit (without r/ prefix). Optional fields parameter for performance (default: ["id", "username", "totalKarma"]). Available fields: id, username, profileUrl, profilePicUrl, snoovatarImg, linkKarma, commentKarma, totalKarma, profileDescription, and more. AGGREGATE FIELDS (from matching posts) - MUST BE EXPLICITLY REQUESTED IN FIELDS: aggRelevance (relevance score for sorting), relevantPostsCount (count of matching posts per user), relevantPostsUpvotesSum, relevantPostsCommentsCountSum. These return aggregated metrics from all matched posts for each user. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters16

query	string	required	Full-text search of Reddit post titles and content to find users who authored matching posts. Searches posts, returns UNIQUE user authors (deduplicated). EXACT PHRASES: Wrap in double quotes - "machine learning" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - python tutorial help. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use "python tutorial" AND beginner (not "python tutorial beginner"). Use programming OR coding (not "programming coding"). PARENTHESES: Group terms for precise logic - (python OR javascript) AND ("web development" NOT framework). FORBIDDEN: DO NOT use filter operators with colons (from:, to:, since:, until:) - use dedicated parameters instead. Query examples: "machine learning" \| python help \| "data science" AND visualization \| (gaming OR esports) NOT "mobile games"
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional	Start date filter (YYYY-MM-DD format)
endDate	string	optional	End date filter (YYYY-MM-DD format)
subreddit	string	optional	Filter results to a specific subreddit (without r/ prefix)
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "totalKarma"]. AVAILABLE FIELDS: Core: id, username, profileUrl, profilePicUrl, snoovatarImg. Karma: linkKarma, commentKarma, totalKarma, awardeeKarma, awarderKarma. Status: isGold, isMod, isEmployee, hasVerifiedEmail, isSuspended, verified, isBlocked, acceptFollowers, hasSubscribed, hideFromRobots, prefShowSnoovatar. Profile: profileDescription, profileBannerUrl, profileTitle. Timestamps: createdAt, createdAtTimestamp, createdAtDate. Aggregations (from matching posts): aggRelevance (relevance score), relevantPostsCount (count of matching posts), relevantPostsUpvotesSum, relevantPostsCommentsCountSum. EXAMPLES: ["id", "username"] for minimal, ["username", "totalKarma", "relevantPostsCount", "relevantPostsUpvotesSum"] to include engagement aggregations.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Full-text search of Reddit post titles and content to find users who authored matching posts. Searches posts, returns UNIQUE user authors (deduplicated). EXACT PHRASES: Wrap in double quotes - \"machine learning\" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - python tutorial help. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use \"python tutorial\" AND beginner (not \"python tutorial beginner\"). Use programming OR coding (not \"programming coding\"). PARENTHESES: Group terms for precise logic - (python OR javascript) AND (\"web development\" NOT framework). FORBIDDEN: DO NOT use filter operators with colons (from:, to:, since:, until:) - use dedicated parameters instead. Query examples: \"machine learning\" | python help | \"data science\" AND visualization | (gaming OR esports) NOT \"mobile games\""
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string",
      "description": "Start date filter (YYYY-MM-DD format)"
    },
    "endDate": {
      "type": "string",
      "description": "End date filter (YYYY-MM-DD format)"
    },
    "subreddit": {
      "type": "string",
      "description": "Filter results to a specific subreddit (without r/ prefix)"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"totalKarma\"]. AVAILABLE FIELDS: Core: id, username, profileUrl, profilePicUrl, snoovatarImg. Karma: linkKarma, commentKarma, totalKarma, awardeeKarma, awarderKarma. Status: isGold, isMod, isEmployee, hasVerifiedEmail, isSuspended, verified, isBlocked, acceptFollowers, hasSubscribed, hideFromRobots, prefShowSnoovatar. Profile: profileDescription, profileBannerUrl, profileTitle. Timestamps: createdAt, createdAtTimestamp, createdAtDate. Aggregations (from matching posts): aggRelevance (relevance score), relevantPostsCount (count of matching posts), relevantPostsUpvotesSum, relevantPostsCommentsCountSum. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"totalKarma\", \"relevantPostsCount\", \"relevantPostsUpvotesSum\"] to include engagement aggregations."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getRedditPostsByKeywords

Search Reddit posts by keywords with two response modes. Searches in post titles and selftext. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: sentiment analysis, subreddit trends, community discussions across thousands of posts. Returns by default: id, title, authorUsername, subredditName, createdAtDate. First searches database, then external API if data is stale or missing. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). Date filters: OMIT startDate/endDate parameters by default. ONLY pass these if user explicitly requests specific date range (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FILTERS: sort (relevance, hot, top, new, comments), time (hour, day, week, month, year, all), subreddit (limit to specific subreddit). FIELDS parameter (optional): Specify to get additional/different fields. Available: Core (id, title, selftext, url, permalink), Author (authorId, authorUsername), Subreddit (subredditName, subredditId), Engagement (score, upvotes, downvotes, upvoteRatio, commentsCount, crosspostsCount), Flags (isSelf, isVideo, over18, spoiler, locked, stickied, archived). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters18

query	string	required	Full-text search of post content. Searches post titles and selftext. EXACT PHRASES: Wrap in double quotes - "machine learning" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - AI robotics blockchain. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use "deep learning" AND python (not "deep learning python"). Use tensorflow OR pytorch (not "tensorflow pytorch"). PARENTHESES: Group terms for precise logic - (AI OR "artificial intelligence") AND ethics. Query examples: "climate change" \| AI OR blockchain \| "neural networks" AND python \| (startup OR entrepreneur)
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
sort	string	optional	Sort order for results. Default: relevance.
time	string	optional	Time filter for results. Default: all.
subreddit	string	optional	Filter posts by subreddit name (without r/ prefix). Use this parameter to limit search to a specific subreddit. Example: subreddit="wallstreetbets" finds all posts in r/wallstreetbets.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "title", "authorUsername", "subredditName", "createdAtDate"]. AVAILABLE FIELDS: Core: id, title, selftext, url, permalink, postUrl, thumbnail. Author: authorId, authorUsername. Subreddit: subredditName, subredditId. Engagement: score, upvotes, downvotes, upvoteRatio, commentsCount, crosspostsCount. Flags: isSelf, isVideo, isOriginalContent, over18, spoiler, locked, stickied, archived. Meta: linkFlairText, postHint, domain, crosspostParent. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: ["id", "title", "score"] for minimal, ["title", "selftext", "score", "commentsCount"] for content analysis.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Full-text search of post content. Searches post titles and selftext. EXACT PHRASES: Wrap in double quotes - \"machine learning\" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - AI robotics blockchain. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use \"deep learning\" AND python (not \"deep learning python\"). Use tensorflow OR pytorch (not \"tensorflow pytorch\"). PARENTHESES: Group terms for precise logic - (AI OR \"artificial intelligence\") AND ethics. Query examples: \"climate change\" | AI OR blockchain | \"neural networks\" AND python | (startup OR entrepreneur)"
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "sort": {
      "type": "string",
      "enum": [
        "relevance",
        "hot",
        "top",
        "new",
        "comments"
      ],
      "description": "Sort order for results. Default: relevance."
    },
    "time": {
      "type": "string",
      "enum": [
        "hour",
        "day",
        "week",
        "month",
        "year",
        "all"
      ],
      "description": "Time filter for results. Default: all."
    },
    "subreddit": {
      "type": "string",
      "description": "Filter posts by subreddit name (without r/ prefix). Use this parameter to limit search to a specific subreddit. Example: subreddit=\"wallstreetbets\" finds all posts in r/wallstreetbets."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"title\", \"authorUsername\", \"subredditName\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, title, selftext, url, permalink, postUrl, thumbnail. Author: authorId, authorUsername. Subreddit: subredditName, subredditId. Engagement: score, upvotes, downvotes, upvoteRatio, commentsCount, crosspostsCount. Flags: isSelf, isVideo, isOriginalContent, over18, spoiler, locked, stickied, archived. Meta: linkFlairText, postHint, domain, crosspostParent. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: [\"id\", \"title\", \"score\"] for minimal, [\"title\", \"selftext\", \"score\", \"commentsCount\"] for content analysis."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getRedditPostWithCommentsById

Get Reddit post by ID with its comments. Returns both the post data and comments in a single response. FAST (default, omit responseType or responseType="fast"): Returns post and up to 300 comments directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100 comments/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. RESPONSE STRUCTURE: Returns { results: { post: {...}, comments: [...] }, count, guidance }. PAGING MODE DETAILS: FIRST CALL: Omit pageNumber and tableName. Creates cached table for comments, returns page 1 with post data and pagination metadata. SUBSEQUENT PAGES: Use tableName from first response with pageNumber (2, 3, etc.) to fetch additional comment pages. Post data is NOT returned on subsequent pages. FIELD SELECTION: Use postFields for post data optimization, commentFields for comment data optimization. First searches database for both post and comments, then external API if data is stale or missing. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters13

postId	string	required	Reddit post ID to fetch. Returns the post data along with its comments.
postFields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "title", "authorUsername", "subredditName", "createdAtDate"]. AVAILABLE FIELDS: Core: id, title, selftext, url, permalink, postUrl, thumbnail. Author: authorId, authorUsername. Subreddit: subredditName, subredditId. Engagement: score, upvotes, downvotes, upvoteRatio, commentsCount, crosspostsCount. Flags: isSelf, isVideo, isOriginalContent, over18, spoiler, locked, stickied, archived. Meta: linkFlairText, postHint, domain, crosspostParent. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: ["id", "title", "score"] for minimal, ["title", "selftext", "score", "commentsCount"] for content analysis.
commentFields	array	optional	PERFORMANCE OPTIMIZATION: Specify comment fields you need. DEFAULT (if omitted): ["id", "body", "authorUsername", "createdAtDate"]. AVAILABLE FIELDS: Core: id, body, parentPostId, parentId. Author: authorId, authorUsername. Subreddit: postSubredditName, postSubredditId. Engagement: score, upvotes, downvotes, controversiality. Meta: depth, isSubmitter, stickied, collapsed, edited, distinguished. Timestamps: createdAt, createdAtTimestamp, createdAtDate.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "minLength": 1,
      "description": "Reddit post ID to fetch. Returns the post data along with its comments."
    },
    "postFields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"title\", \"authorUsername\", \"subredditName\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, title, selftext, url, permalink, postUrl, thumbnail. Author: authorId, authorUsername. Subreddit: subredditName, subredditId. Engagement: score, upvotes, downvotes, upvoteRatio, commentsCount, crosspostsCount. Flags: isSelf, isVideo, isOriginalContent, over18, spoiler, locked, stickied, archived. Meta: linkFlairText, postHint, domain, crosspostParent. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: [\"id\", \"title\", \"score\"] for minimal, [\"title\", \"selftext\", \"score\", \"commentsCount\"] for content analysis."
    },
    "commentFields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify comment fields you need. DEFAULT (if omitted): [\"id\", \"body\", \"authorUsername\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, body, parentPostId, parentId. Author: authorId, authorUsername. Subreddit: postSubredditName, postSubredditId. Engagement: score, upvotes, downvotes, controversiality. Meta: depth, isSubmitter, stickied, collapsed, edited, distinguished. Timestamps: createdAt, createdAtTimestamp, createdAtDate."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getRedditCommentsByKeywords

Search Reddit comments by keywords. Searches in comment body text. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: sentiment analysis, discussion trends, community opinions across thousands of comments. DATABASE-ONLY: Searches existing database records only. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). Date filters: OMIT startDate/endDate parameters by default. ONLY pass these if user explicitly requests specific date range (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FILTERS: subreddit (limit to specific subreddit without r/ prefix). Optional fields parameter for performance: ["id", "body", "authorUsername", "postSubredditName", "score", "createdAtDate"]. Returns by default: id, body, authorUsername, createdAtDate. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters14

query	string	required	Full-text search of comment content. Searches comment body text. EXACT PHRASES: Wrap in double quotes - "machine learning" matches that exact phrase. KEYWORDS: Without quotes, matches comments containing any of the words - AI robotics blockchain. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use "deep learning" AND python (not "deep learning python"). Use tensorflow OR pytorch (not "tensorflow pytorch"). PARENTHESES: Group terms for precise logic - (AI OR "artificial intelligence") AND ethics. Query examples: "climate change" \| AI OR blockchain \| "neural networks" AND python \| (startup OR entrepreneur)
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
subreddit	string	optional	Filter comments by subreddit name (without r/ prefix). Use this parameter to limit search to comments from a specific subreddit. Example: subreddit="wallstreetbets" finds all comments in r/wallstreetbets.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify comment fields you need. DEFAULT (if omitted): ["id", "body", "authorUsername", "createdAtDate"]. AVAILABLE FIELDS: Core: id, body, parentPostId, parentId. Author: authorId, authorUsername. Subreddit: postSubredditName, postSubredditId. Engagement: score, upvotes, downvotes, controversiality. Meta: depth, isSubmitter, stickied, collapsed, edited, distinguished. Timestamps: createdAt, createdAtTimestamp, createdAtDate.
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Full-text search of comment content. Searches comment body text. EXACT PHRASES: Wrap in double quotes - \"machine learning\" matches that exact phrase. KEYWORDS: Without quotes, matches comments containing any of the words - AI robotics blockchain. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use \"deep learning\" AND python (not \"deep learning python\"). Use tensorflow OR pytorch (not \"tensorflow pytorch\"). PARENTHESES: Group terms for precise logic - (AI OR \"artificial intelligence\") AND ethics. Query examples: \"climate change\" | AI OR blockchain | \"neural networks\" AND python | (startup OR entrepreneur)"
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "subreddit": {
      "type": "string",
      "description": "Filter comments by subreddit name (without r/ prefix). Use this parameter to limit search to comments from a specific subreddit. Example: subreddit=\"wallstreetbets\" finds all comments in r/wallstreetbets."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify comment fields you need. DEFAULT (if omitted): [\"id\", \"body\", \"authorUsername\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, body, parentPostId, parentId. Author: authorId, authorUsername. Subreddit: postSubredditName, postSubredditId. Engagement: score, upvotes, downvotes, controversiality. Meta: depth, isSubmitter, stickied, collapsed, edited, distinguished. Timestamps: createdAt, createdAtTimestamp, createdAtDate."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

searchRedditSubreddits

Search Reddit subreddits by keywords using real-time external API. Searches subreddit names and descriptions to find communities. Use for: Discovering communities about topics, finding niche subreddits, exploring Reddit communities. Optional fields parameter for performance (default: ["id", "displayName", "title", "subscribersCount"]). Available fields: id, displayName, title, publicDescription, description, subscribersCount, activeUserCount, subredditType, over18, lang, url, subredditUrl, iconImg, bannerImg, headerImg, communityIcon, createdAt. Returns: array of matching subreddits (default 50, max 50) with id, name, description, subscriber count. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

query	string	required	Search query for Reddit subreddits. Searches subreddit names and descriptions.
limit	integer	optional	Maximum number of subreddits to return. Default: 50, Max: 50.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "displayName", "title", "subscribersCount"]. AVAILABLE FIELDS: Core: id, displayName, title, publicDescription, description. Stats: subscribersCount, activeUserCount. Meta: subredditType, over18, lang, url, subredditUrl. Images: iconImg, bannerImg, headerImg, communityIcon. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: ["id", "displayName", "subscribersCount"] for minimal, ["displayName", "publicDescription", "subscribersCount", "activeUserCount"] for discovery.
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Search query for Reddit subreddits. Searches subreddit names and descriptions."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Maximum number of subreddits to return. Default: 50, Max: 50."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"displayName\", \"title\", \"subscribersCount\"]. AVAILABLE FIELDS: Core: id, displayName, title, publicDescription, description. Stats: subscribersCount, activeUserCount. Meta: subredditType, over18, lang, url, subredditUrl. Images: iconImg, bannerImg, headerImg, communityIcon. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: [\"id\", \"displayName\", \"subscribersCount\"] for minimal, [\"displayName\", \"publicDescription\", \"subscribersCount\", \"activeUserCount\"] for discovery."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getRedditSubredditWithPostsByName

Get Reddit subreddit by name with its posts. FAST (default, omit responseType or responseType="fast"): Returns subreddit data with up to 300 posts directly (use limit param to reduce). Auto API fallback for fresh data. PAGING (responseType="paging"): Async paginated results (100 posts per page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. RESPONSE STRUCTURE: Returns { results: { subreddit: {...}, posts: [...] }, pagination: {...} }. FIELD SELECTION: Use subredditFields for subreddit data optimization, postFields for post data optimization. First searches database for both subreddit and posts, then external API if data is stale or missing. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters13

subredditName	string	required	Reddit subreddit name to fetch (without r/ prefix). Example: "wallstreetbets", "programming". Returns the subreddit data along with its posts.
subredditFields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "displayName", "title", "subscribersCount"]. AVAILABLE FIELDS: Core: id, displayName, title, publicDescription, description. Stats: subscribersCount, activeUserCount. Meta: subredditType, over18, lang, url, subredditUrl. Images: iconImg, bannerImg, headerImg, communityIcon. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: ["id", "displayName", "subscribersCount"] for minimal, ["displayName", "publicDescription", "subscribersCount", "activeUserCount"] for discovery.
postFields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "title", "authorUsername", "subredditName", "createdAtDate"]. AVAILABLE FIELDS: Core: id, title, selftext, url, permalink, postUrl, thumbnail. Author: authorId, authorUsername. Subreddit: subredditName, subredditId. Engagement: score, upvotes, downvotes, upvoteRatio, commentsCount, crosspostsCount. Flags: isSelf, isVideo, isOriginalContent, over18, spoiler, locked, stickied, archived. Meta: linkFlairText, postHint, domain, crosspostParent. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: ["id", "title", "score"] for minimal, ["title", "selftext", "score", "commentsCount"] for content analysis.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "subredditName": {
      "type": "string",
      "description": "Reddit subreddit name to fetch (without r/ prefix). Example: \"wallstreetbets\", \"programming\". Returns the subreddit data along with its posts."
    },
    "subredditFields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"displayName\", \"title\", \"subscribersCount\"]. AVAILABLE FIELDS: Core: id, displayName, title, publicDescription, description. Stats: subscribersCount, activeUserCount. Meta: subredditType, over18, lang, url, subredditUrl. Images: iconImg, bannerImg, headerImg, communityIcon. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: [\"id\", \"displayName\", \"subscribersCount\"] for minimal, [\"displayName\", \"publicDescription\", \"subscribersCount\", \"activeUserCount\"] for discovery."
    },
    "postFields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"title\", \"authorUsername\", \"subredditName\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, title, selftext, url, permalink, postUrl, thumbnail. Author: authorId, authorUsername. Subreddit: subredditName, subredditId. Engagement: score, upvotes, downvotes, upvoteRatio, commentsCount, crosspostsCount. Flags: isSelf, isVideo, isOriginalContent, over18, spoiler, locked, stickied, archived. Meta: linkFlairText, postHint, domain, crosspostParent. Timestamps: createdAt, createdAtTimestamp, createdAtDate. EXAMPLES: [\"id\", \"title\", \"score\"] for minimal, [\"title\", \"selftext\", \"score\", \"commentsCount\"] for content analysis."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "subredditName"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getRedditSubredditsByKeywords

Search for SUBREDDITS where Reddit posts match keywords. Returns unique, deduplicated subreddit profiles. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce). Auto API fallback for fresh data. PAGING (responseType="paging"): Async paginated results (100 per page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). FILTERS: - startDate/endDate: Filter by post date (YYYY-MM-DD format). OMIT by default, only use if user explicitly requests date range. IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Optional fields parameter for performance (default: ["id", "displayName", "title", "subscribersCount"]). Available fields: id, displayName, title, publicDescription, description, subscribersCount, activeUserCount, and more. AGGREGATE FIELDS (from matching posts) - MUST BE EXPLICITLY REQUESTED IN FIELDS: aggRelevance (relevance score for sorting), relevantPostsCount (count of matching posts per subreddit), relevantPostsUpvotesSum, relevantPostsCommentsCountSum. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

query	string	required	Full-text search of Reddit post titles and content to find subreddits where matching posts were made. Searches posts, returns UNIQUE subreddits (deduplicated). EXACT PHRASES: Wrap in double quotes - "machine learning" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - python tutorial help. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use "python tutorial" AND beginner (not "python tutorial beginner"). Use programming OR coding (not "programming coding"). PARENTHESES: Group terms for precise logic - (python OR javascript) AND ("web development" NOT framework). FORBIDDEN: DO NOT use filter operators with colons (from:, to:, since:, until:) - use dedicated parameters instead. Query examples: "machine learning" \| python help \| "data science" AND visualization \| (gaming OR esports) NOT "mobile games"
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional	Start date filter (YYYY-MM-DD format)
endDate	string	optional	End date filter (YYYY-MM-DD format)
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "displayName", "title", "subscribersCount"]. AVAILABLE FIELDS: Core: id, displayName, title, publicDescription, description. Stats: subscribersCount, activeUserCount. Meta: subredditType, over18, lang, url, subredditUrl. Images: iconImg, bannerImg, headerImg, communityIcon. Timestamps: createdAt, createdAtTimestamp, createdAtDate. Aggregations (from matching posts): aggRelevance (relevance score), relevantPostsCount (count of matching posts), relevantPostsUpvotesSum, relevantPostsCommentsCountSum. EXAMPLES: ["id", "displayName", "subscribersCount"] for minimal, ["displayName", "subscribersCount", "relevantPostsCount", "relevantPostsUpvotesSum"] to include engagement aggregations.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Full-text search of Reddit post titles and content to find subreddits where matching posts were made. Searches posts, returns UNIQUE subreddits (deduplicated). EXACT PHRASES: Wrap in double quotes - \"machine learning\" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words - python tutorial help. BOOLEAN OPERATORS: MUST explicitly use the keywords AND, OR, NOT (uppercase or lowercase). NO implicit operators - space between words means OR by default. Examples requiring explicit operators: Use \"python tutorial\" AND beginner (not \"python tutorial beginner\"). Use programming OR coding (not \"programming coding\"). PARENTHESES: Group terms for precise logic - (python OR javascript) AND (\"web development\" NOT framework). FORBIDDEN: DO NOT use filter operators with colons (from:, to:, since:, until:) - use dedicated parameters instead. Query examples: \"machine learning\" | python help | \"data science\" AND visualization | (gaming OR esports) NOT \"mobile games\""
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string",
      "description": "Start date filter (YYYY-MM-DD format)"
    },
    "endDate": {
      "type": "string",
      "description": "End date filter (YYYY-MM-DD format)"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"displayName\", \"title\", \"subscribersCount\"]. AVAILABLE FIELDS: Core: id, displayName, title, publicDescription, description. Stats: subscribersCount, activeUserCount. Meta: subredditType, over18, lang, url, subredditUrl. Images: iconImg, bannerImg, headerImg, communityIcon. Timestamps: createdAt, createdAtTimestamp, createdAtDate. Aggregations (from matching posts): aggRelevance (relevance score), relevantPostsCount (count of matching posts), relevantPostsUpvotesSum, relevantPostsCommentsCountSum. EXAMPLES: [\"id\", \"displayName\", \"subscribersCount\"] for minimal, [\"displayName\", \"subscribersCount\", \"relevantPostsCount\", \"relevantPostsUpvotesSum\"] to include engagement aggregations."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTiktokUser

Get Tiktok user profile by ID or username. Use identifierType="id" for numeric user ID, identifierType="username" for username. For username: Use ONLY when you have the precise username. For person names or fuzzy search, use searchTiktokUsers instead. Optional fields parameter for performance (default: ["id", "username", "nickname"]). Available fields: id, username, nickname, signature, isPrivate, isVerified, followerCount, followingCount, likeCount, postCount, avatar, and more. Returns: single user profile. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters9

identifier	string	required	User ID (numeric) or username depending on identifierType.
identifierType	string	required	Type of identifier provided. Use "id" for numeric user ID, "username" for username.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "nickname"]. AVAILABLE FIELDS: Core: id, username, nickname, signature, secUid, avatar, isPrivate, isVerified. Engagement: followerCount, followingCount, likeCount, postCount. Meta: language, region, createdAt, usernameModifyTime. EXAMPLES: ["id", "username"] for minimal, ["username", "nickname", "followerCount"] for basic info.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "minLength": 1,
      "description": "User ID (numeric) or username depending on identifierType."
    },
    "identifierType": {
      "type": "string",
      "enum": [
        "id",
        "username"
      ],
      "description": "Type of identifier provided. Use \"id\" for numeric user ID, \"username\" for username."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"nickname\"]. AVAILABLE FIELDS: Core: id, username, nickname, signature, secUid, avatar, isPrivate, isVerified. Engagement: followerCount, followingCount, likeCount, postCount. Meta: language, region, createdAt, usernameModifyTime. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"nickname\", \"followerCount\"] for basic info."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "identifier",
    "identifierType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

searchTiktokUsers

Search Tiktok users by name or username via external API. Use for: Name-based search, finding multiple candidates, fuzzy matching, discovering users. NOT for: Exact username lookup (use getTiktokUser when username is certain). Optional fields parameter for performance (default: ["id", "username", "nickname"]). Returns: array of matching users (default 10, max 10). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

name	string	required	Search query for Tiktok users. Supports partial name or username matching.
limit	number	optional	Maximum number of users to return. Default: 10, Max: 10.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "nickname"]. AVAILABLE FIELDS: Core: id, username, nickname, signature, secUid, avatar, isPrivate, isVerified. Engagement: followerCount, followingCount, likeCount, postCount. Meta: language, region, createdAt, usernameModifyTime. EXAMPLES: ["id", "username"] for minimal, ["username", "nickname", "followerCount"] for basic info.
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Search query for Tiktok users. Supports partial name or username matching."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 10,
      "description": "Maximum number of users to return. Default: 10, Max: 10."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"nickname\"]. AVAILABLE FIELDS: Core: id, username, nickname, signature, secUid, avatar, isPrivate, isVerified. Engagement: followerCount, followingCount, likeCount, postCount. Meta: language, region, createdAt, usernameModifyTime. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"nickname\", \"followerCount\"] for basic info."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTiktokUsersByKeywords

Search for USERS who authored Tiktok posts matching keywords. USE CASE: Find users who have posted content about specific topics. Returns unique, deduplicated user profiles. RESPONSE MODES (responseType parameter): "fast" (DEFAULT): Returns up to 300 results directly in one call. Use limit param to reduce. Best for quick lookups. "paging": Async paginated results (100/page). Returns operation ID - call checkOperationStatus to get results. Use pageNumber/tableName for subsequent pages. "csv": Async CSV export. Returns dataDumpExportOperationId - call checkOperationStatus to get S3 download link. Best for bulk export. PAGING MODE DETAILS: FIRST CALL: Omit pageNumber and tableName. Creates cached table, returns page 1 with pagination metadata (tableName, totalPages, totalRows). SUBSEQUENT PAGES: Use tableName from first response with pageNumber (2, 3, etc.). BULK FETCH: Use pageNumberEnd with pageNumber and tableName for multiple consecutive pages. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). FILTERS: startDate/endDate (YYYY-MM-DD format). OMIT by default. IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Optional fields parameter for performance (default: ["id", "username", "nickname"]). AGGREGATE FIELDS (from matching posts) - MUST BE EXPLICITLY REQUESTED IN FIELDS: aggRelevance, relevantPostsCount, relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsPlaysSum, relevantPostsForwardsSum. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

query	string	required	Full-text search of Tiktok post descriptions to find users who authored matching posts. Searches posts, returns UNIQUE user authors (deduplicated). EXACT PHRASES: Wrap in double quotes - "sustainable fashion" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words. BOOLEAN OPERATORS: Use AND, OR, NOT explicitly. PARENTHESES: Group terms - (travel OR adventure) AND "sustainable living". FORBIDDEN: DO NOT use filter operators with colons. Query examples: "climate change" \| fashion OR beauty \| "digital nomad" AND remote
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "nickname"]. AVAILABLE FIELDS: Core: id, username, nickname, signature, secUid, avatar, isPrivate, isVerified. Engagement: followerCount, followingCount, likeCount, postCount. Meta: language, region, createdAt, usernameModifyTime. Aggregations (from matching posts): aggRelevance, relevantPostsCount, relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsPlaysSum, relevantPostsForwardsSum. EXAMPLES: ["id", "username"] for minimal, ["username", "nickname", "followerCount", "relevantPostsCount"] to include engagement aggregations.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Full-text search of Tiktok post descriptions to find users who authored matching posts. Searches posts, returns UNIQUE user authors (deduplicated). EXACT PHRASES: Wrap in double quotes - \"sustainable fashion\" matches that exact phrase. KEYWORDS: Without quotes, matches posts containing any of the words. BOOLEAN OPERATORS: Use AND, OR, NOT explicitly. PARENTHESES: Group terms - (travel OR adventure) AND \"sustainable living\". FORBIDDEN: DO NOT use filter operators with colons. Query examples: \"climate change\" | fashion OR beauty | \"digital nomad\" AND remote"
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"nickname\"]. AVAILABLE FIELDS: Core: id, username, nickname, signature, secUid, avatar, isPrivate, isVerified. Engagement: followerCount, followingCount, likeCount, postCount. Meta: language, region, createdAt, usernameModifyTime. Aggregations (from matching posts): aggRelevance, relevantPostsCount, relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsPlaysSum, relevantPostsForwardsSum. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"nickname\", \"followerCount\", \"relevantPostsCount\"] to include engagement aggregations."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTiktokUsersByHashtags

Search for USERS who authored Tiktok posts tagged with specific hashtags. USE CASE: Find users who have posted content tagged with one or more hashtags. Returns unique, deduplicated user profiles. Pass hashtags as an array of bare alphanumeric strings - do NOT include leading "#". OR semantics: matches users who posted content tagged with ANY of the listed hashtags. RESPONSE MODES (responseType parameter): "fast" (DEFAULT): Returns up to 300 results directly in one call. Use limit param to reduce. Best for quick lookups. "paging": Async paginated results (100/page). Returns operation ID - call checkOperationStatus to get results. Use pageNumber/tableName for subsequent pages. "csv": Async CSV export. Returns dataDumpExportOperationId - call checkOperationStatus to get S3 download link. Best for bulk export. NOT for keyword/phrase search in descriptions - use getTiktokUsersByKeywords instead. FILTERS: startDate/endDate (YYYY-MM-DD format). OMIT by default. IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Optional fields parameter for performance (default: ["id", "username", "nickname"]). AGGREGATE FIELDS (from matching posts) - MUST BE EXPLICITLY REQUESTED IN FIELDS: aggRelevance, relevantPostsCount, relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsPlaysSum, relevantPostsForwardsSum. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

hashtags	array	required	Array of hashtags to search for (1-5 per request). OR semantics: matches users who posted content containing ANY of the listed hashtags. Bare alphanumeric/underscore only - do NOT include leading "#". Examples: ["dance", "fyp"] \| ["cooking"] \| ["sustainable_fashion"].
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "username", "nickname"]. AVAILABLE FIELDS: Core: id, username, nickname, signature, secUid, avatar, isPrivate, isVerified. Engagement: followerCount, followingCount, likeCount, postCount. Meta: language, region, createdAt, usernameModifyTime. Aggregations (from matching posts): aggRelevance, relevantPostsCount, relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsPlaysSum, relevantPostsForwardsSum. EXAMPLES: ["id", "username"] for minimal, ["username", "nickname", "followerCount", "relevantPostsCount"] to include engagement aggregations.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "hashtags": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_]{1,500}$"
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "Array of hashtags to search for (1-5 per request). OR semantics: matches users who posted content containing ANY of the listed hashtags. Bare alphanumeric/underscore only - do NOT include leading \"#\". Examples: [\"dance\", \"fyp\"] | [\"cooking\"] | [\"sustainable_fashion\"]."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once (e.g., pageNumber=1, pageNumberEnd=5 fetches pages 1-5). Must be >= pageNumber. Omit to fetch single page only. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"username\", \"nickname\"]. AVAILABLE FIELDS: Core: id, username, nickname, signature, secUid, avatar, isPrivate, isVerified. Engagement: followerCount, followingCount, likeCount, postCount. Meta: language, region, createdAt, usernameModifyTime. Aggregations (from matching posts): aggRelevance, relevantPostsCount, relevantPostsLikesSum, relevantPostsCommentsSum, relevantPostsPlaysSum, relevantPostsForwardsSum. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"nickname\", \"followerCount\", \"relevantPostsCount\"] to include engagement aggregations."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original prompt to improve result relevance, detect implicit requirements, and apply intelligent caching. Omitting this may result in suboptimal or incomplete results."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "hashtags"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTiktokPostsByIds

Get multiple Tiktok posts by IDs (1-100 IDs per request). Returns results directly. First searches database, then external API for missing/stale data. Optional fields parameter for performance: ["id", "description", "likeCount"]. Returns: results array with id, description, userId, username, createdAtDate, engagement metrics. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

postIds	array	required	Array of Tiktok post IDs to fetch (1-100 IDs). Returns only found posts, omitting not-found IDs.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "description", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: ["id", "description"] for minimal, ["id", "description", "username", "createdAtDate", "likeCount", "playCount"] for basic analysis, ["id", "description", "hashtags", "duration", "videoUrl"] for video content analysis.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postIds": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\d{1,50}$"
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Array of Tiktok post IDs to fetch (1-100 IDs). Returns only found posts, omitting not-found IDs."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"description\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: [\"id\", \"description\"] for minimal, [\"id\", \"description\", \"username\", \"createdAtDate\", \"likeCount\", \"playCount\"] for basic analysis, [\"id\", \"description\", \"hashtags\", \"duration\", \"videoUrl\"] for video content analysis."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postIds"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTiktokPostsByUser

Get posts from Tiktok user by ID or username with three response modes. Use identifierType="id" for numeric user ID, identifierType="username" for username. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. Results include guidance for full mode. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: engagement analysis, content trends, viral video detection, processing thousands of posts. Returns by default: id, description, username, createdAtDate. First searches database, then external API if data is stale or missing. Date filters: OMIT startDate/endDate parameters by default to retrieve all posts. ONLY pass these if user explicitly requests specific date range (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FIELDS parameter (optional): Specify to get additional/different fields. Available: Core (id, description, userId, username, nickname, createdAtDate), Engagement (likeCount, commentCount, playCount, forwardCount, collectCount, downloadCount), Media (videoThumbnail, videoUrl, duration, postType), Content (hashtags, transcriptsJson). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters16

identifier	string	required	User ID (numeric) or username depending on identifierType.
identifierType	string	required	Type of identifier provided. Use "id" for numeric user ID, "username" for username.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "description", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: ["id", "description"] for minimal, ["id", "description", "username", "createdAtDate", "likeCount", "playCount"] for basic analysis, ["id", "description", "hashtags", "duration", "videoUrl"] for video content analysis.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "minLength": 1,
      "description": "User ID (numeric) or username depending on identifierType."
    },
    "identifierType": {
      "type": "string",
      "enum": [
        "id",
        "username"
      ],
      "description": "Type of identifier provided. Use \"id\" for numeric user ID, \"username\" for username."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"description\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: [\"id\", \"description\"] for minimal, [\"id\", \"description\", \"username\", \"createdAtDate\", \"likeCount\", \"playCount\"] for basic analysis, [\"id\", \"description\", \"hashtags\", \"duration\", \"videoUrl\"] for video content analysis."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "identifier",
    "identifierType"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTiktokPostsByKeywords

Search Tiktok posts by keywords with three response modes. Searches post descriptions and video transcripts. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: trend analysis, hashtag tracking, viral content discovery across Tiktok. Returns by default: id, description, username, createdAtDate. NOT for URL lookups or post ID lookups - use getTiktokPostsByIds instead. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). Date filters: OMIT startDate/endDate parameters by default to retrieve all posts. ONLY pass these if user explicitly requests specific date range (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FIELDS parameter (optional): Specify to get additional/different fields. Available: Core (id, description, userId, username, nickname, createdAtDate), Engagement (likeCount, commentCount, playCount, forwardCount, collectCount, downloadCount), Media (videoThumbnail, videoUrl, duration, postType), Content (hashtags, transcriptsJson). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

query	string	required	Plain text keywords or phrases to search in post descriptions. Use double quotes for exact phrases. Do NOT pass URLs or post IDs. Examples: "dance challenge", cooking OR recipe, "sunset" AND beach
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "description", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: ["id", "description"] for minimal, ["id", "description", "username", "createdAtDate", "likeCount", "playCount"] for basic analysis, ["id", "description", "hashtags", "duration", "videoUrl"] for video content analysis.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Plain text keywords or phrases to search in post descriptions. Use double quotes for exact phrases. Do NOT pass URLs or post IDs. Examples: \"dance challenge\", cooking OR recipe, \"sunset\" AND beach"
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"description\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: [\"id\", \"description\"] for minimal, [\"id\", \"description\", \"username\", \"createdAtDate\", \"likeCount\", \"playCount\"] for basic analysis, [\"id\", \"description\", \"hashtags\", \"duration\", \"videoUrl\"] for video content analysis."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTiktokPostsByHashtags

Search Tiktok posts by hashtags with three response modes. Searches the hashtags column directly (NOT post descriptions). Pass hashtags as an array of bare alphanumeric strings - do NOT include leading "#". OR semantics: matches posts containing ANY of the listed hashtags. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: hashtag trend analysis, viral hashtag tracking, cross-hashtag content discovery. Returns by default: id, description, username, createdAtDate. NOT for keyword/phrase search in descriptions - use getTiktokPostsByKeywords instead. NOT for URL or post ID lookups - use getTiktokPostsByIds instead. Date filters: OMIT startDate/endDate parameters by default to retrieve all posts. ONLY pass these if user explicitly requests specific date range (YYYY-MM-DD format). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FIELDS parameter (optional): Specify to get additional/different fields. Available: Core (id, description, userId, username, nickname, createdAtDate), Engagement (likeCount, commentCount, playCount, forwardCount, collectCount, downloadCount), Media (videoThumbnail, videoUrl, duration, postType), Content (hashtags, transcriptsJson). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

hashtags	array	required	Array of hashtags to search for (1-5 per request). OR semantics: matches posts containing ANY of the listed hashtags. Bare alphanumeric/underscore only - do NOT include leading "#". Examples: ["dance", "fyp", "viral"] \| ["cooking"] \| ["sustainable_fashion"].
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "description", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: ["id", "description"] for minimal, ["id", "description", "username", "createdAtDate", "likeCount", "playCount"] for basic analysis, ["id", "description", "hashtags", "duration", "videoUrl"] for video content analysis.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "hashtags": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_]{1,500}$"
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "Array of hashtags to search for (1-5 per request). OR semantics: matches posts containing ANY of the listed hashtags. Bare alphanumeric/underscore only - do NOT include leading \"#\". Examples: [\"dance\", \"fyp\", \"viral\"] | [\"cooking\"] | [\"sustainable_fashion\"]."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"description\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: [\"id\", \"description\"] for minimal, [\"id\", \"description\", \"username\", \"createdAtDate\", \"likeCount\", \"playCount\"] for basic analysis, [\"id\", \"description\", \"hashtags\", \"duration\", \"videoUrl\"] for video content analysis."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "hashtags"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

searchTiktokSounds

Search Tiktok sounds/music by keyword. Use to discover sound/music objects (by title, artist, or album), then pass the returned id to getTiktokPostsBySound to find posts using that sound. Optional fields parameter (default: ["id", "title", "author", "userCount"]). Returns: array of sounds (up to 300) with id, title, author, userCount. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters8

keyword	string	required	Search query for Tiktok sounds/music. Matches sound title, artist, or album name.
limit	number	optional	Maximum number of sounds to return. Default: 300, Max: 300.
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "title", "author", "userCount"]. AVAILABLE FIELDS: id, title, author, album, duration (seconds), userCount (number of posts using the sound), isOriginal, isCommerceMusic, isOriginalSound.
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "keyword": {
      "type": "string",
      "minLength": 1,
      "description": "Search query for Tiktok sounds/music. Matches sound title, artist, or album name."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 300,
      "description": "Maximum number of sounds to return. Default: 300, Max: 300."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"title\", \"author\", \"userCount\"]. AVAILABLE FIELDS: id, title, author, album, duration (seconds), userCount (number of posts using the sound), isOriginal, isCommerceMusic, isOriginalSound."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "keyword"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTiktokPostsBySound

Get Tiktok posts that use a specific sound/music with three response modes. Required: soundId (numeric ID from searchTiktokSounds). FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. Returns by default: id, description, username, createdAtDate. NOT for keyword/phrase search - use getTiktokPostsByKeywords. NOT for hashtags - use getTiktokPostsByHashtags. Date filters: OMIT startDate/endDate by default. ONLY pass if user explicitly requests a date range (YYYY-MM-DD). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. FIELDS parameter (optional): Core (id, description, userId, username, nickname, createdAtDate), Engagement (likeCount, commentCount, playCount, forwardCount, collectCount, downloadCount), Media (videoThumbnail, videoUrl, duration, postType), Content (hashtags, transcriptsJson). This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

soundId	string	required	Tiktok sound/music ID (numeric string). Get IDs from searchTiktokSounds. Example: "7016547803243907841".
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "description", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: ["id", "description"] for minimal, ["id", "description", "username", "createdAtDate", "likeCount", "playCount"] for basic analysis, ["id", "description", "hashtags", "duration", "videoUrl"] for video content analysis.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "soundId": {
      "type": "string",
      "pattern": "^\\d{1,50}$",
      "description": "Tiktok sound/music ID (numeric string). Get IDs from searchTiktokSounds. Example: \"7016547803243907841\"."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"description\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, postType, isPrivate, userId, username, nickname, description, descriptionLanguage, createdAt, createdAtTimestamp, createdAtDate. Engagement: collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount. Media: videoThumbnail, videoUrl (array of video URLs), duration (video length in seconds). Content: hashtags (array of hashtag strings). EXAMPLES: [\"id\", \"description\"] for minimal, [\"id\", \"description\", \"username\", \"createdAtDate\", \"likeCount\", \"playCount\"] for basic analysis, [\"id\", \"description\", \"hashtags\", \"duration\", \"videoUrl\"] for video content analysis."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "soundId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTiktokCommentsByPostId

Get COMMENT CONTENT (text, likes) for a Tiktok post. Returns the actual comment objects with text and metadata. RETURNS COMMENT DATA: id, text, username, createdAtDate, likeCount. Use for reading what people said. FAST (default, omit responseType or responseType="fast"): Returns up to 300 results directly (use limit param to reduce, e.g. limit=5). Auto API fallback for fresh data. PAGING (responseType="paging"): Async paginated results (100/page), returns operationId for polling via checkOperationStatus. Supports pageNumber/tableName for subsequent pages. CSV (responseType="csv"): Async single CSV download, returns operationId, poll for S3 link. CODE EXECUTION: For csv mode, download CSV and use code execution to analyze full dataset. Ideal for: sentiment analysis, reading discussions, analyzing comment content, engagement patterns. Date filters: OMIT startDate/endDate by default. ONLY pass if user explicitly requests date range. IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Optional fields: ["id", "text", "username", "createdAtDate", "likeCount"]. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data.

Parameters15

postId	string	required	Tiktok post ID to fetch comments for.
pageNumber	number	optional	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
pageNumberEnd	number	optional	Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName.
tableName	string	optional	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
startDate	string	optional
endDate	string	optional
fields	array	optional	PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): ["id", "text", "username", "createdAtDate"]. AVAILABLE FIELDS: Core: id, text, postId, userId, username, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount. EXAMPLES: ["id", "text"] for minimal, ["id", "text", "username", "createdAtDate", "likeCount"] for basic analysis.
forceLatest	boolean	optional	USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., "get the latest", "most recent", "real-time"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching).
responseType	string	optional	Response mode. "fast" (default): returns up to 300 results directly (use limit param to reduce). "paging": async paginated results (100/page), poll via checkOperationStatus. "csv": async single CSV download, poll for S3 link.
limit	number	optional	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
userPrompt	string	optional	CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "minLength": 1,
      "description": "Tiktok post ID to fetch comments for."
    },
    "pageNumber": {
      "type": "number",
      "minimum": 1,
      "description": "Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page."
    },
    "pageNumberEnd": {
      "type": "number",
      "minimum": 1,
      "description": "Optional ending page number for fetching multiple consecutive pages at once. Must be >= pageNumber. Requires tableName."
    },
    "tableName": {
      "type": "string",
      "description": "Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "PERFORMANCE OPTIMIZATION: Specify fields you need. DEFAULT (if omitted): [\"id\", \"text\", \"username\", \"createdAtDate\"]. AVAILABLE FIELDS: Core: id, text, postId, userId, username, createdAt, createdAtTimestamp, createdAtDate. Engagement: likeCount. EXAMPLES: [\"id\", \"text\"] for minimal, [\"id\", \"text\", \"username\", \"createdAtDate\", \"likeCount\"] for basic analysis."
    },
    "forceLatest": {
      "type": "boolean",
      "description": "USE SPARINGLY: Force fetching the latest data from the API, bypassing cache checks. Only use when explicitly required (e.g., \"get the latest\", \"most recent\", \"real-time\"). WARNING: Increases latency and API costs. Default: false (uses intelligent caching)."
    },
    "responseType": {
      "type": "string",
      "enum": [
        "fast",
        "paging",
        "csv"
      ],
      "description": "Response mode. \"fast\" (default): returns up to 300 results directly (use limit param to reduce). \"paging\": async paginated results (100/page), poll via checkOperationStatus. \"csv\": async single CSV download, poll for S3 link."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 500000,
      "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K)."
    },
    "userPrompt": {
      "type": "string",
      "description": "CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getUserAccessKey

Retrieve authenticated user access key. Required: authentication, confirmation. Returns: access key, metadata.

Parameters3

confirmRetrieval	boolean	required	Must be true to retrieve key. Security confirmation required.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "confirmRetrieval": {
      "type": "boolean",
      "description": "Must be true to retrieve key. Security confirmation required."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    }
  },
  "required": [
    "confirmRetrieval"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

checkAccessKeyStatus

Check access key status without revealing key. Required: authentication. Returns: status, metadata.

Parameters2

feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getTrackedItems

Get tracked keywords and users. Returns: phrase, type (keyword/user/subreddit/hashtag), platform (twitter/instagram/reddit/tiktok). Subreddit is Reddit-only, hashtag is TikTok-only.

Parameters4

feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

addTrackedItems

Add keywords/users to track. Accepts array of items with phrase, type (keyword/user/subreddit/hashtag), platform (twitter/instagram/reddit/tiktok). Subreddit is Reddit-only, hashtag is TikTok-only. Returns error if plan limit exceeded.

Parameters5

items	array	required	Array of items to track. Each item has phrase, type, and platform.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "phrase": {
            "type": "string",
            "minLength": 1,
            "description": "The keyword, username, subreddit name, or hashtag."
          },
          "type": {
            "type": "string",
            "enum": [
              "keyword",
              "user",
              "subreddit",
              "hashtag"
            ],
            "description": "Type of tracked item: \"keyword\", \"user\", \"subreddit\" (Reddit only), or \"hashtag\" (TikTok only)."
          },
          "platform": {
            "type": "string",
            "enum": [
              "twitter",
              "instagram",
              "reddit",
              "tiktok"
            ],
            "description": "Platform: \"twitter\", \"instagram\", \"reddit\", or \"tiktok\"."
          }
        },
        "required": [
          "phrase",
          "type",
          "platform"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "description": "Array of items to track. Each item has phrase, type, and platform."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

removeTrackedItems

Remove tracked keywords/users. Accepts array of items with phrase, type (keyword/user/subreddit/hashtag), platform (twitter/instagram/reddit/tiktok). Subreddit is Reddit-only, hashtag is TikTok-only. Use getTrackedItems first to see current items.

Parameters5

items	array	required	Array of tracked items to remove. Use getTrackedItems to see current items.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional
_isTrial	boolean	optional
_trialToken	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "phrase": {
            "type": "string",
            "minLength": 1,
            "description": "The keyword, username, subreddit name, or hashtag."
          },
          "type": {
            "type": "string",
            "enum": [
              "keyword",
              "user",
              "subreddit",
              "hashtag"
            ],
            "description": "Type of tracked item: \"keyword\", \"user\", \"subreddit\" (Reddit only), or \"hashtag\" (TikTok only)."
          },
          "platform": {
            "type": "string",
            "enum": [
              "twitter",
              "instagram",
              "reddit",
              "tiktok"
            ],
            "description": "Platform: \"twitter\", \"instagram\", \"reddit\", or \"tiktok\"."
          }
        },
        "required": [
          "phrase",
          "type",
          "platform"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "description": "Array of tracked items to remove. Use getTrackedItems to see current items."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    },
    "_isTrial": {
      "type": "boolean"
    },
    "_trialToken": {
      "type": "string"
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getAccountDetails

Get authenticated user's account details: plan (name, features), billing (period, next renewal date; null for Free plan), and usage (subscription credits remaining, extra credits remaining, extra tracked items). Required: authentication. Returns: nested plan/billing/usage object.

Parameters2

feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

getCreditsUsageHistory

Get authenticated user's credits and export-rows usage over time, for analyzing usage patterns. Params: range ("today" | "7d" | "current_month" | "lifetime", default current_month), granularity ("hour" | "day", default day). Returns time-series buckets for both credits and exportRows, each with subscriptionUsed, extraUsed, totalUsed, extraPurchased. Use for trend analysis and spotting usage spikes. For current remaining balances, use getAccountDetails instead. Required: authentication.

Parameters4

range	string	optional	Time window to analyze. "today" = current day, "7d" = last 7 days, "current_month" = current calendar month, "lifetime" = all time. Default: current_month.
granularity	string	optional	Bucket size for the time series. "hour" = hourly buckets (best with range=today or 7d), "day" = daily buckets. Default: day.
feedback	string	optional	Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: "wish getTwitterPostsByKeywords supported language filtering", "auth flow was confusing", "would be useful to have a getTwitterListMembers tool", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
_requestId	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "range": {
      "type": "string",
      "enum": [
        "today",
        "7d",
        "current_month",
        "lifetime"
      ],
      "default": "current_month",
      "description": "Time window to analyze. \"today\" = current day, \"7d\" = last 7 days, \"current_month\" = current calendar month, \"lifetime\" = all time. Default: current_month."
    },
    "granularity": {
      "type": "string",
      "enum": [
        "hour",
        "day"
      ],
      "default": "day",
      "description": "Bucket size for the time series. \"hour\" = hourly buckets (best with range=today or 7d), \"day\" = daily buckets. Default: day."
    },
    "feedback": {
      "type": "string",
      "description": "Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about the current tool: you can use this field to comment on a different tool you used earlier, flag missing functionality, request a new tool, or share general impressions. Examples: \"wish getTwitterPostsByKeywords supported language filtering\", \"auth flow was confusing\", \"would be useful to have a getTwitterListMembers tool\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."
    },
    "_requestId": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md8 KBView on GitHub

Xpoz MCP Server

Search Twitter, Instagram, Reddit & TikTok from any AI agent. Billions of posts indexed. Natural language queries. CSV exports up to 500K rows. No API keys needed.

Remote MCP server — no local installation required. Connect via Streamable HTTP and authenticate with OAuth 2.1 (sign in with Google, no API keys to manage). Direct probes to https://mcp.xpoz.ai/mcp return 401 Unauthorized — that's expected; your MCP client handles the OAuth flow.

Quick Start

Claude Desktop / Cursor / Windsurf

Add to your MCP config:

json

{
  "mcpServers": {
    "xpoz": {
      "type": "streamable-http",
      "url": "https://mcp.xpoz.ai/mcp"
    }
  }
}

Claude Code, Codex, Gemini CLI

bash

# Claude Code
claude mcp add --transport http --scope user xpoz https://mcp.xpoz.ai/mcp

# Codex / Gemini CLI: see https://www.xpoz.ai/integrations

OpenClaw

bash

clawhub install xpoz-social-search

Then authenticate via the OAuth link when prompted. More pre-built skills are available — see clawhub.ai/u/atyachin.

Docker (stdio-only clients)

The repository ships a small Docker image that bridges stdio to the remote server through mcp-remote, for clients that can only launch local commands:

bash

docker build -t xpoz-mcp .
docker run -i --rm -e XPOZ_API_KEY=your-key xpoz-mcp

XPOZ_API_KEY is optional: without it the bridge falls back to the OAuth sign-in flow, which needs a browser. Get a key at xpoz.ai/get-token.

SDKs & CLI

If you'd rather call Xpoz directly from code or a terminal instead of through an MCP client:

TypeScript / Node.js

bash

npm install @xpoz/xpoz

Source: XPOZpublic/xpoz-ts-sdk.

Python

bash

pip install xpoz

Source: XPOZpublic/xpoz-python-sdk.

CLI

Platform	Install command
macOS / Linux (Homebrew)	`brew install XPOZpublic/xpoz/xpoz-cli`
macOS / Linux (one-liner)	`curl -fsSL https://raw.githubusercontent.com/XPOZpublic/xpoz-cli/main/install.sh \| sh`
Windows (PowerShell)	`iwr -useb https://raw.githubusercontent.com/XPOZpublic/xpoz-cli/main/install.ps1 \| iex`
Windows (winget)	`winget install Xpoz.XpozCli`
Any platform with Python ≥ 3.10	`pip install xpoz-cli`

Source: XPOZpublic/xpoz-cli.

All four channels speak the same MCP protocol against https://mcp.xpoz.ai/mcp under the hood, so any tool you see below is reachable from every surface. Get an API token at xpoz.ai/get-token.

Platforms & Tools

Twitter / X (14 tools)

Tool	Description
`searchTwitterUsers`	Find users by name, bio, or keywords
`getTwitterUser`	Get profile details (followers, bio, metrics)
`getTwitterUsersByKeywords`	Discover users actively posting about topics
`getTwitterUserConnections`	Get followers or following list
`getTwitterPostsByKeywords`	Search tweets by keywords, hashtags, mentions
`getTwitterPostsByAuthor`	Get tweets from a specific user
`getTwitterPostsByIds`	Fetch specific tweets by ID
`getTwitterPostComments`	Get replies to a tweet
`getTwitterPostRetweets`	Get retweets of a tweet
`getTwitterPostQuotes`	Get quote tweets
`getTwitterPostInteractingUsers`	Users who liked/retweeted a post
`countTweets`	Count tweets matching a query (hourly/daily buckets)
`checkOperationStatus`	Poll async export operations
`cancelOperation`	Cancel a running operation

Instagram (9 tools)

Tool	Description
`searchInstagramUsers`	Find users by name or username
`getInstagramUser`	Get profile details and metrics
`getInstagramUsersByKeywords`	Discover users posting about topics
`getInstagramUserConnections`	Get followers or following list
`getInstagramPostsByKeywords`	Search posts by keywords or hashtags
`getInstagramPostsByUser`	Get posts from a specific user
`getInstagramPostsByIds`	Fetch specific posts by ID
`getInstagramPostInteractingUsers`	Users who liked/commented on a post
`getInstagramCommentsByPostId`	Get comments on a post

Reddit (9 tools)

Tool	Description
`searchRedditUsers`	Find users by name
`getRedditUser`	Get user profile and karma
`getRedditUsersByKeywords`	Discover users active in topics
`getRedditPostsByKeywords`	Search posts across subreddits
`getRedditPostWithCommentsById`	Get a post with its comment tree
`getRedditCommentsByKeywords`	Search comments by keywords
`searchRedditSubreddits`	Find subreddits by name
`getRedditSubredditWithPostsByName`	Get a subreddit's metadata and recent posts
`getRedditSubredditsByKeywords`	Discover subreddits by topic

TikTok (7 tools)

Tool	Description
`searchTiktokUsers`	Find creators by name or username
`getTiktokUser`	Get creator profile (followers, likes, bio, verification)
`getTiktokUsersByKeywords`	Discover creators by topic in their post history
`getTiktokPostsByKeywords`	Search videos by keywords or hashtags
`getTiktokPostsByUser`	Get videos posted by a specific creator
`getTiktokPostsByIds`	Fetch specific videos by ID
`getTiktokCommentsByPostId`	Get comments on a specific video

Tracking & Monitoring (3 tools)

For continuous brand monitoring and lead generation — Xpoz indexes new matching content as it appears.

Tool	Description
`addTrackedItems`	Subscribe to ongoing monitoring of a query, user, or subreddit across any platform
`getTrackedItems`	List your active tracked items with last-update timestamps
`removeTrackedItems`	Stop monitoring tracked items by ID

Key Features

Natural language queries — describe what you want, Xpoz optimizes the search
CSV exports — up to 500K rows in a single download via async operations
Server-side pagination — handle large result sets efficiently
Field selection — request only the fields you need
Cache control — forceLatest: true bypasses cache for real-time data
Async operations — long-running exports with status polling
OAuth 2.1 — dynamic client registration with Google as the upstream identity provider, no API keys to manage

Use Cases

Lead generation — find people discussing problems your product solves
Influencer discovery — identify creators by what they post, not just follower count
Brand monitoring — track mentions, sentiment, and competitor activity
Market research — analyze trends and conversations at scale
Expert finding — discover domain authorities across platforms
Security intelligence — monitor vulnerability discussions before CVEs publish

Discovery surfaces (for AI agents and scanners)

These public, machine-readable endpoints describe Xpoz to crawlers and agentic clients:

Surface	URL
MCP manifest	https://www.xpoz.ai/.well-known/mcp.json
MCP tool catalog (descriptions + JSON-Schema parameters)	https://www.xpoz.ai/.well-known/mcp/tools.json
Agent Skills index (agentskills.io v0.2.0)	https://www.xpoz.ai/.well-known/agent-skills/index.json
`llms.txt`	https://www.xpoz.ai/llms.txt
`llms-full.txt`	https://www.xpoz.ai/llms-full.txt
`discovery.txt`	https://www.xpoz.ai/discovery.txt
Webhooks contract	https://www.xpoz.ai/webhooks
Rate limits & 429 contract	https://www.xpoz.ai/rate-limits

License

This repository contains configuration and documentation only. The Xpoz MCP server is a hosted service — see Terms of Service.

Install

Tools (51)

getTwitterUsersgetTwitterUsersearchTwitterUsersgetTwitterUserConnectionsgetTwitterUsersByKeywordsgetTwitterPostsByIdsgetTwitterPostsByAuthorgetTwitterPostsByKeywords

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.xpoz.ai/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "social-insights": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.xpoz.ai/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

ai.xpoz/social-insights MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

getTwitterUsers

getTwitterUser

searchTwitterUsers

getTwitterUserConnections

getTwitterUsersByKeywords

getTwitterPostsByIds

getTwitterPostsByAuthor

getTwitterPostsByKeywords

getTwitterPostRetweets

getTwitterPostQuotes

getTwitterPostComments

countTweets

getTwitterPostInteractingUsers

checkOperationStatus

cancelOperation

getInstagramPostsByIds

getInstagramPostsByUser

getInstagramPostsByKeywords

getInstagramUser

searchInstagramUsers

getInstagramUserConnections

getInstagramPostInteractingUsers

getInstagramUsersByKeywords

getInstagramCommentsByPostId

getRedditUser

searchRedditUsers

getRedditUsersByKeywords

getRedditPostsByKeywords

getRedditPostWithCommentsById

getRedditCommentsByKeywords

searchRedditSubreddits

getRedditSubredditWithPostsByName

getRedditSubredditsByKeywords

getTiktokUser

searchTiktokUsers

getTiktokUsersByKeywords

getTiktokUsersByHashtags

getTiktokPostsByIds

getTiktokPostsByUser

getTiktokPostsByKeywords

getTiktokPostsByHashtags

searchTiktokSounds

getTiktokPostsBySound

getTiktokCommentsByPostId

getUserAccessKey

checkAccessKeyStatus

getTrackedItems

addTrackedItems

removeTrackedItems

getAccountDetails

getCreditsUsageHistory

Xpoz MCP Server

Quick Start

Claude Desktop / Cursor / Windsurf

Claude Code, Codex, Gemini CLI

OpenClaw

Docker (stdio-only clients)

SDKs & CLI

TypeScript / Node.js

Python

CLI

Platforms & Tools

Twitter / X (14 tools)

Instagram (9 tools)

Reddit (9 tools)

TikTok (7 tools)

Tracking & Monitoring (3 tools)

Key Features

Use Cases

Discovery surfaces (for AI agents and scanners)

Links

License

Install

Remote endpoint