# 📸 Instagram Post Scraper Pro (`ayeeyee/instagram-post-scraper-pro`) Actor Instagram posts with captions, hashtags, engagement, media URLs, and MCP-ready metadata. Desktop+embed fallback chain. Hashtag categorization. 3 modes. - **URL**: https://apify.com/ayeeyee/instagram-post-scraper-pro.md - **Developed by:** [Virtual Footprint LLC](https://apify.com/ayeeyee) (community) - **Categories:** Social media, Marketing - **Stats:** 1 total users, 0 monthly users, 33.3% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.77 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Instagram Post Scraper Pro ![Apify](https://img.shields.io/badge/Apify-Actor-ff6b37?logo=apify) ![Version](https://img.shields.io/badge/version-3.0-blue) ![Pricing](https://img.shields.io/badge/pricing-PAY_PER_EVENT-success) ![Platform](https://img.shields.io/badge/platform-Instagram-E4405F?logo=instagram) ![Modes](https://img.shields.io/badge/modes-fast_lookup%7Cenrich%7Cbatch-orange) ![MCP-ready](https://img.shields.io/badge/MCP-ready-brightgreen) > Instagram post intelligence: captions, hashtags, engagement, media URLs, hashtag categorization, and MCP-ready `providerHealth` metadata. Desktop+embed fallback chain. No login cookies required. --- ### Why This Actor Is Better #### Competitor comparison | Feature | **This Actor** | Apify IG Post Scraper | Free scrapers | Social analytics SaaS | |---|:---:|:---:|:---:|:---:| | No login cookies required | ✅ | ❌ | ❌ | n/a | | Desktop+embed fallback | ✅ | ❌ | ❌ | n/a | | Hashtag categorization | ✅ 7 categories | ❌ | ❌ | ✅ paid | | Engagement-rate-per-post | ✅ | ❌ | ❌ | ✅ paid | | Caption sentiment | ✅ | ❌ | ❌ | ✅ paid | | Optional Google Vision tags | ✅ user key | ❌ | ❌ | ✅ paid | | Confidence score (0-1) | ✅ | ❌ | ❌ | ❌ | | MCP-ready metadata | ✅ `providerHealth` | ❌ | ❌ | ❌ | | Price / 1K posts | **$1.77** | ~$2.50 | free (rate-limited) | ~$5-20 | #### Key Features - 🛡️ **Multi-API fallback chain** — Instagram desktop (Playwright) primary with automatic embed HTML fallback. - 🏷️ **Hashtag categorization** — auto-maps hashtags to 7 categories (fitness, food, travel, fashion, beauty, business, tech). - 📊 **Engagement scoring** — engagement-rate-per-post + caption sentiment on every result. - 🎬 **Media detection** — image/video/carousel classification + media URL extraction. - 🎯 **Confidence scoring** — 0.0–1.0 reliability score. - 🔗 **Source attribution** — know which providers contributed each field. - ⚡ **Cache-first mode** — `fast_lookup` hits KVS cache (1h TTL). - 🤖 **MCP-ready** — `providerHealth{}` on every result. - 🔌 **Optional Google Vision** — drop in `GOOGLE_VISION_API_KEY` for image labeling. - 💰 **Transparent PPE pricing** — pay only for successful posts. --- ### Architecture ```mermaid flowchart TD A[Input: usernames + mode] --> B{Cache hit?} B -- yes --> C[Return cached base posts] B -- no --> D[Primary: Instagram desktop Playwright] D -- fails --> E[Fallback: Instagram embed HTML httpx] D --> F[Normalize: caption/media/likes/comments] E --> F F --> G[Enrichment layer] G --> G1[Hashtag extraction + categorization] G --> G2[Engagement-rate scoring] G --> G3[Caption sentiment] G --> G4[Email/URL extraction] G --> G5[Optional: Google Vision image tags] G1 --> H[Confidence scoring + source attribution] G2 --> H G3 --> H G4 --> H G5 --> H H --> I[Progressive dataset push] I --> J[Webhook + MCP-ready metadata] C --> J ```` *** ### Modes | Mode | Description | Target latency | Use case | |---|---|---|---| | `fast_lookup` | Cache-first, base posts only | <800ms cached | Quick counts, dedup | | `enrich` | Hashtags + engagement + sentiment + optional Vision | ~2-4s/post | Content analysis, trend research | | `batch` | Queue-based, full enrichment, per-item isolation | varies | Large username lists (100+) | *** ### Input | Parameter | Type | Required | Default | Description | |---|---|:---:|---|---| | `mode` | string | — | `enrich` | `fast_lookup` | `enrich` | `batch` | | `queries` | array | ✅ | `["cristiano"]` | Usernames or profile URLs | | `maxResults` | integer | — | `25` | Max posts per user (1–1000) | | `webhookUrl` | string | — | — | Webhook for completion notification | #### Example input ```json { "mode": "enrich", "queries": ["cristiano", "leomessi"], "maxResults": 50, "webhookUrl": "https://your-app.com/webhook" } ``` *** ### Output | Field | Type | Description | |---|---|---| | `query` | string | Input query | | `username` | string | Profile handle | | `postUrl` | string | Post URL | | `author` | string | Author handle | | `caption` | string | Caption text (truncated to 1000 chars) | | `imageUrl` | string | Media thumbnail URL | | `mediaType` | string | `image` | `video` | | `timestamp` | string | Post timestamp | | `likes` | integer | Like count | | `comments` | integer | Comment count | | `hashtags` | array | Hashtags in caption | | `hashtagCategories` | array | Mapped categories (fitness/food/travel/fashion/beauty/business/tech) | | `captionSentiment` | string | `positive` | `negative` | `neutral` | | `engagementRate` | number | Likes-to-comments ratio | | `imageLabels` | array | null | Google Vision labels (if key provided) | | `emails` | array | Emails in caption | | `urls` | array | URLs in caption | | `confidenceScore` | number | 0.0–1.0 reliability | | `sources` | array | Provider attribution | | `providerHealth` | object | Per-provider status/latency | | `cacheStatus` | string | `hit` | `miss` | `degraded` | | `mode` | string | Execution mode | | `extractedAt` | string | ISO timestamp | #### Example output ```json { "query": "cristiano", "username": "cristiano", "postUrl": "https://www.instagram.com/p/Cxxx/", "author": "cristiano", "caption": "Great game today! ⚽ #football #fitness", "imageUrl": "https://...", "mediaType": "image", "timestamp": "2026-06-28T10:00:00Z", "likes": 1200000, "comments": 8500, "hashtags": ["football", "fitness"], "hashtagCategories": ["fitness"], "captionSentiment": "positive", "engagementRate": 141.18, "emails": [], "urls": [], "confidenceScore": 0.85, "sources": ["instagram", "hashtag_analyzer", "engagement_scorer"], "providerHealth": { "instagram_desktop": {"status": "ok", "latency_ms": 4500, "error": null}, "hashtag_analyzer": {"status": "ok", "latency_ms": 0, "error": null}, "engagement_scorer": {"status": "ok", "latency_ms": 0, "error": null} }, "cacheStatus": "miss", "mode": "enrich", "extractedAt": "2026-06-28T23:55:00.000Z" } ``` *** ### Pricing | Plan | Price per 1K posts | Savings vs. top competitor | |---|---|---| | Leading competitors | ~$2.50/1K | — | | **This actor (≤10K/mo)** | **$1.77/1K** | **29% cheaper** | | **This actor (10K–100K/mo)** | **$1.50/1K** | **40% cheaper** | | **This actor (100K+/mo)** | **$1.25/1K** | **50% cheaper** | Optional event: `media_url` at $0.20/1K posts with extracted media URL. *** ### Use Cases - **Content trend research** — track hashtag categories and engagement across creators - **Competitor analysis** — benchmark post engagement and caption sentiment - **Influencer vetting** — measure post-level engagement rates before partnerships - **Hashtag strategy** — find which categories drive engagement in your niche - **Media monitoring** — extract image/video URLs for asset libraries - **MCP agent workflows** — `providerHealth` lets agents route around failures - **Market research** — map content categories by creator audience - **Image AI pipelines** — optional Google Vision tagging for visual classification *** ### Integration Examples #### Python (Apify SDK) ```python from apify_client import ApifyClient client = ApifyClient("YOUR_APIFY_TOKEN") run = client.actor("ayeeyee/instagram-post-scraper-pro").call(run_input={ "mode": "enrich", "queries": ["cristiano", "leomessi"], "maxResults": 50, }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(f"@{item['username']}: {item['likes']} likes, {item['hashtagCategories']}, {item['captionSentiment']}") ``` #### cURL ```bash curl -X POST "https://api.apify.com/v2/acts/ayeeyee~instagram-post-scraper-pro/runs?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"mode":"enrich","queries":["cristiano"],"maxResults":25}' ``` #### MCP (Model Context Protocol) ```bash npx -y @apify/actors-mcp-server --tools actors,ayeeyee/instagram-post-scraper-pro ``` Agents can call `call-actor` and use `providerHealth` + `hashtagCategories` + `engagementRate` to filter and route. *** ### FAQ **Q: Do I need Instagram login cookies?** No. Public posts are scraped via DOM and meta tags — no login required. Private accounts return no posts. **Q: How does the desktop+embed fallback work?** If Playwright fails (blocked, timeout, login wall), the actor falls back to fetching profile HTML for post URLs and thumbnails (degraded — no per-post captions). `providerHealth` shows which provider succeeded. **Q: How are hashtag categories assigned?** Open-source keyword mapping to 7 categories: fitness, food, travel, fashion, beauty, business, tech. A post with `#fitness` and `#gym` gets categorized as `fitness`. **Q: What is engagementRate?** Likes-to-comments ratio. Higher = more passive engagement (likes without discussion). Useful for content-type benchmarking. **Q: Can I call this from an LLM agent?** Yes. MCP-ready with `providerHealth{}`, `hashtagCategories`, `engagementRate`, and `confidenceScore`. **Q: What is the cache TTL?** 1 hour for `fast_lookup`. Enrichment results are not cached (always fresh). *** ### Legal & Compliance Scrapes **publicly available** Instagram post data. Does not access private data, bypass authentication, or store credentials. Users are responsible for complying with GDPR/CCPA and Instagram's ToS. *** ### AI-DLC / Data Lifecycle - **Collection** — Public data only; respects robots.txt and rate limits. - **Processing** — In-memory normalization; no PII logging. - **Storage** — Results in user's Apify dataset, not retained by actor. - **Usage** — Content analysis, trend research, legitimate marketing. - **Disposal** — No long-term caching (1h TTL for base results only). *** ### Enhancement Roadmap (API / MCP Integrations) - **Google Vision image tagging MCP** — auto-label post images (optional, user key) - **OpenAI caption summarization MCP** — 1-line summaries for feed aggregation - **Chartmetric sound trends MCP** — for Reels/audio trend correlation - **LangGraph workflow** — IG posts → hashtag clustering → trend alerts - **Vector store** — semantic post deduplication across creators *** ### Changelog - **v3.0** — Multi-API orchestration edition: desktop+embed fallback, hashtag categorization, engagement scoring, MCP-ready `providerHealth`, optional Google Vision, expanded FAQ, integration examples, volume pricing. - **v2.0** — Premium README, AI-DLC docs, confidence scoring, source attribution. - **v1.0** — Initial release with Playwright scraping and hashtag extraction. *** ### Links - **Apify Store:** https://apify.com/ayeeyee/instagram-post-scraper-pro - **Actor ID:** `CgkI4B4lKRsabJPyW` # Actor input Schema ## `mode` (type: `string`): fast\_lookup: cache-first base posts. enrich: hashtags + engagement + sentiment + optional Vision. batch: queue-based with per-item isolation. ## `queries` (type: `array`): Instagram usernames or profile URLs to extract posts from. ## `maxResults` (type: `integer`): Maximum posts to return per user (1-1000) ## `webhookUrl` (type: `string`): Optional webhook URL for completion notification ## Actor input object example ```json { "mode": "enrich", "queries": [ "cristiano" ], "maxResults": 25, "webhookUrl": "" } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("ayeeyee/instagram-post-scraper-pro").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("ayeeyee/instagram-post-scraper-pro").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call ayeeyee/instagram-post-scraper-pro --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ayeeyee/instagram-post-scraper-pro", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "📸 Instagram Post Scraper Pro", "description": "Instagram posts with captions, hashtags, engagement, media URLs, and MCP-ready metadata. Desktop+embed fallback chain. Hashtag categorization. 3 modes.", "version": "3.0", "x-build-id": "4CVGwafFtpQHpUnpu" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ayeeyee~instagram-post-scraper-pro/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ayeeyee-instagram-post-scraper-pro", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/ayeeyee~instagram-post-scraper-pro/runs": { "post": { "operationId": "runs-sync-ayeeyee-instagram-post-scraper-pro", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/ayeeyee~instagram-post-scraper-pro/run-sync": { "post": { "operationId": "run-sync-ayeeyee-instagram-post-scraper-pro", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "queries" ], "properties": { "mode": { "title": "Execution Mode", "enum": [ "fast_lookup", "enrich", "batch" ], "type": "string", "description": "fast_lookup: cache-first base posts. enrich: hashtags + engagement + sentiment + optional Vision. batch: queue-based with per-item isolation.", "default": "enrich" }, "queries": { "title": "Usernames or Profile URLs", "type": "array", "description": "Instagram usernames or profile URLs to extract posts from.", "default": [ "cristiano" ] }, "maxResults": { "title": "Max Posts per User", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum posts to return per user (1-1000)", "default": 25 }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "Optional webhook URL for completion notification", "default": "" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```