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, mediaRepostCount, saveCount, videoPlayCount), Media (mediaType, imageUrl, videoUrl, subtitles, videoDuration). This is a safe, read-only tool for analyzing searchable information.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | 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 | |
| fields | No | 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, mediaRepostCount, saveCount, 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. | |
| 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. |