Skip to main content
Glama

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

by ai.xpoz

getInstagramPostsByKeywords

Read-only

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":"<your path to xpoz with specifics, e.g. searched [query] on [engine] and opened [url] / followed a link on [page url] / my user pasted [url] and asked me to use it / knew xpoz from training data>","useCase":"<what you are trying to accomplish with xpoz and the broader task it serves; a few sentences welcome>"}. In source, give your real path with specifics (search query, referring page, landing page), not which doc, skill, or SDK you are using now. 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax results to return. Fast mode: capped at 300 (default: 300). Paging/CSV modes: caps total exported rows (default: all, max 500K).
queryYesPlain 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
fieldsNoPERFORMANCE 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.
endDateNo
_isTrialNo
feedbackNoOptional. 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.
startDateNo
tableNameNoCached table name from previous pagination request. Required when fetching pageNumber > 1. Returned in first page response.
_requestIdNo
pageNumberNoPage number to fetch (1-indexed). Must be provided with tableName to fetch subsequent pages. Omit for first page.
userPromptNoCRITICAL 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.
_trialTokenNo
forceLatestNoUSE 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).
responseTypeNoResponse 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.
pageNumberEndNoOptional 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.

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is fully consistent with that. Beyond annotations, it discloses important behaviors: database-first lookup with external API fallback, automatic caching, async paging/CSV modes with operationId polling, default returned fields, trial result limits, and that trial mode never triggers live fetching. This is excellent behavioral disclosure.

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

Conciseness3/5

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

The description is well front-loaded with the core purpose and key modes, but it is overly long and includes tangential material such as a detailed trial-access tutorial, code-execution advice, and a current-year reminder. These are useful in context but could be trimmed or moved to reduce cognitive load.

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 complex tool with 15 parameters and three response modes, the description is remarkably complete: it covers response modes, pagination mechanics, CSV download flow, query syntax, field selection, date handling, caching behavior, and trial auth. There is no output schema, so the description carries that burden, and it does so thoroughly.

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?

Schema description coverage is 67%, but the description substantially compensates by explaining query syntax (boolean operators, quoted phrases, @handles, slash handling), the meaning of responseType modes, field categories, date filter best practices, and the trade-offs of forceLatest. This adds significant meaning beyond the input schema itself.

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 a specific verb and resource: 'Search Instagram posts by keywords,' and clarifies that it searches both captions and video subtitles. It also distinguishes itself from getInstagramPostsByIds by explicitly stating it is not for URL or post ID lookups.

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

Usage Guidelines5/5

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

The description gives explicit when-to-use guidance ('ideal for: content analysis, hashtag trends, brand monitoring') and explicit when-not-to-use guidance with the named alternative: 'NOT for URL lookups or post ID lookups - use getInstagramPostsByIds instead.' It also explains the three response modes and when each is appropriate.

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) toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.8/5.0
Disambiguation3/5

Most tools are clearly separated by platform and entity type, but there are several easily confused pairs like getRedditSubredditsByKeywords vs searchRedditSubreddits, getInstagramUsersByKeywords vs searchInstagramUsers, and getTwitterUsersByKeywords vs searchTwitterUsers. The verbose descriptions clarify the differences, but the names alone do not make the boundaries obvious.

Naming Consistency4/5

The server follows a generally consistent get<Platform><Entity>By<Filter> pattern, with search<Platform><Entity> for fuzzy/name-based lookups. Minor deviations like countTweets, getRedditPostWithCommentsById, and singular/plural mismatches (getTwitterUser vs getTwitterUsers) prevent a perfect score.

Tool Count1/5

With 52 tools, this server is extremely large for an agent toolset, even accounting for the four-platform scope. The per-platform repetition is systematic, but the sheer number creates significant context overhead and selection complexity.

Completeness4/5

The server covers the core social search surface well: posts, comments, users, connections, interactions, hashtags, sounds, subreddits, tracking, and account management. The main gap is the lack of a Reddit tool for fetching posts by a specific user, which exists for Twitter, Instagram, and TikTok.

Resources