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

getInstagramUsersByKeywords

Read-only

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, relevantPostsMediaRepostsSum, relevantPostsSavesSum, 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.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
`query`	Yes	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"
`fields`	No	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, relevantPostsMediaRepostsSum, relevantPostsSavesSum, relevantPostsVideoPlaysSum. EXAMPLES: ["id", "username"] for minimal, ["username", "fullName", "followerCount", "relevantPostsLikesSum", "relevantPostsCount"] to include engagement aggregations.
`endDate`	No
`_isTrial`	No
`feedback`	No	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 tool that lists the members of a Twitter list", "loved how fast this was". Captured for product feedback; does not affect tool behavior.
`startDate`	No
`tableName`	No	Cached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
`_requestId`	No
`pageNumber`	No	Page number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
`userPrompt`	No	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.
`_trialToken`	No
`forceLatest`	No	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`	No	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.
`pageNumberEnd`	No	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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 2, 2026

changedInput schema / properties / fields / description

Previous value: -"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."New value: +"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, relevantPostsMediaRepostsSum, relevantPostsSavesSum, relevantPostsVideoPlaysSum. EXAMPLES: [\"id\", \"username\"] for minimal, [\"username\", \"fullName\", \"followerCount\", \"relevantPostsLikesSum\", \"relevantPostsCount\"] to include engagement aggregations."

Changed1 schema field changedAug 23, 2026

changedInput schema / properties / feedback / description

Previous value: -"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."New value: +"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 tool that lists the members of a Twitter list\", \"loved how fast this was\". Captured for product feedback; does not affect tool behavior."

Changed7 schema fields changedJul 27, 2026

addedInput schema / properties / _isTrial
```
Added value: +{
+  "type": "boolean"
+}
```
addedInput schema / properties / _trialToken
```
Added value: +{
+  "type": "string"
+}
```

addedInput schema / properties / feedback

Added value: +{
+  "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.",
+  "type": "string"
+}

changedInput schema / properties / fields / description

Previous value: -"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. Timestamps: lastFetch, lastFetchDatetime, xLastUpdated. 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."New value: +"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."

addedInput schema / properties / limit

Added value: +{
+  "description": "Max results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).",
+  "maximum": 500000,
+  "minimum": 1,
+  "type": "number"
+}

addedInput schema / properties / query / maxLength
```
Added value: +250
```

addedInput schema / properties / responseType

Added value: +{
+  "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.",
+  "enum": [
+    "fast",
+    "paging",
+    "csv"
+  ],
+  "type": "string"
+}

First observedJan 31, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the annotations (readOnlyHint=true, destructiveHint=false) by explicitly stating 'This is a safe, read-only tool'. It discloses critical behaviors: response modes (fast/paging/csv) and their async nature, pagination mechanics (cached table, pageNumber/tableName), query syntax limitations (forward slashes as spaces, no column operators), and the 2026 date warning. These are not inferable from annotations and significantly reduce risk of misuse.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but well-structured with clear sections (USE CASE, RESPONSE MODES, PAGING MODE DETAILS, QUERY SYNTAX, FILTERS, IMPORTANT, AGGREGATE FIELDS). It is front-loaded with the core purpose. Some redundancy exists (e.g., response mode details repeated in the main text and in schema parameter descriptions), and the date warning could be tightened, but the complexity of the tool justifies the length. It remains readable and organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 15 parameters, three response modes, and complex query syntax, the description is remarkably complete. It covers return structure ('results array of unique user profiles, count', pagination object, operation IDs), field selection behavior, date filtering, and edge cases (forward slashes, boolean operator requirements). No output schema exists, so the description carries the full burden, and it does so effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 67% schema coverage, the description adds substantial parameter meaning: it explains responseType options in depth, clarifies that limit caps differ by mode, details the interplay of pageNumber/tableName/pageNumberEnd, warns about forceLatest cost, and emphasizes userPrompt's role in NLP optimization. It also elaborates on aggregate fields semantics (from matching posts, not all posts). This far exceeds the schema's descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Search for USERS who authored Instagram posts matching keywords' – a specific verb, resource, and scope. It distinguishes this user-focused search from sibling tools like getInstagramPostsByKeywords by clarifying it returns unique user profiles, and from searchInstagramUsers by the keyword-matching mechanism. The purpose is unambiguous and immediately clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit USE CASE and detailed guidance on when to use each response mode (fast vs paging vs csv), with conditions like 'Best for quick lookups' and 'Best for bulk export'. It also instructs on when to omit date filters ('only use if user explicitly requests date range') and warns about year miscalculation. However, it does not explicitly name alternative sibling tools or state 'use this instead of X', so it falls short of a full 5 but is highly actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

getInstagramUsersByKeywords

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources