# Instagram Bot Detector (`automation-lab/instagram-bot-detector`) Actor 🤖 Audit Instagram profiles for fake-follower and bot-like risk with transparent scores, engagement signals, and reason tags. - **URL**: https://apify.com/automation-lab/instagram-bot-detector.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Social media, AI, Marketing - **Stats:** 4 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 Bot Detector Audit Instagram profiles for fake-follower and bot-risk signals with transparent, CSV-friendly heuristics. ### What does Instagram Bot Detector do? Instagram Bot Detector checks public Instagram profiles and returns one audit row per profile. It calculates profile-level signals such as follower/following balance, post count, recent engagement, and unusual activity patterns. It then produces a `botScore` from 0 to 1, a `riskLevel`, a `confidence` value, and machine-readable `reasonTags`. The actor is designed for influencer vetting, creator screening, and repeat portfolio monitoring. ### Who is it for? Influencer marketing agencies can screen creator shortlists before outreach. Brand partnerships teams can compare sponsorship candidates before committing budget. Creator platforms can run lightweight account-quality checks during onboarding. Marketplaces can add a transparent review step before sending profiles to human reviewers. Analysts can export audit rows to spreadsheets, BI tools, or CRM workflows. ### Why use this actor? 🤖 It focuses on bot-risk analysis, not raw Instagram scraping. 📊 It returns flat rows that are easy to filter and export. 🧠 It includes reason tags instead of an opaque score only. 🔁 It supports bulk usernames and profile URLs. ⚠️ It keeps unavailable/private results visible instead of silently hiding them. ### What data can I extract? | Field | Description | | --- | --- | | `username` | Instagram handle that was audited | | `profileUrl` | Canonical Instagram profile URL | | `status` | `ok`, `private`, `unavailable`, or `error` | | `displayName` | Public display name when available | | `bio` | Public biography text when available | | `followers` | Public follower count | | `following` | Public following count | | `postsCount` | Public media count | | `isPrivate` | Whether Instagram marks the account private | | `isVerified` | Whether Instagram marks the account verified | | `recentPostsSampled` | Number of recent posts used for engagement signals | | `avgLikes` | Average likes across sampled recent posts | | `avgComments` | Average comments across sampled recent posts | | `engagementRate` | `(avgLikes + avgComments) / followers` | | `followerFollowingRatio` | Followers divided by following | | `postFrequencySignals` | Posting cadence flags | | `botScore` | Heuristic bot-risk score from 0 to 1 | | `riskLevel` | `low`, `medium`, `high`, or `unknown` | | `confidence` | Confidence in the available evidence | | `reasonTags` | Transparent reasons behind the score | | `sampledAt` | Audit timestamp | ### How much does it cost to detect Instagram bots? The actor uses pay-per-event pricing. There is a small run start event and a per-profile audit event. The target price is about $0.50 per 1,000 audited profiles before subscription-tier discounts. Large runs are usually cheaper per profile because the fixed start event is spread across more audits. Always check the Apify pricing panel for the live tiered price before running large batches. ### How to use Instagram Bot Detector 1. Open the actor on Apify. 2. Add Instagram usernames such as `instagram`, `natgeo`, or `@creatorname`. 3. Optionally add profile URLs such as `https://www.instagram.com/instagram/`. 4. Keep the default profile limit low for your first test. 5. Run the actor. 6. Open the dataset and review `botScore`, `riskLevel`, `confidence`, and `reasonTags`. 7. Export the dataset to CSV, JSON, Excel, or your preferred integration. ### Input options #### Instagram usernames Use this field for plain handles. The actor accepts usernames with or without the `@` prefix. Duplicate usernames are removed automatically. #### Instagram profile URLs Use this field when your source data already stores full profile URLs. The actor extracts the username from standard Instagram profile URLs. Post, reel, TV, and story URLs are not profile audits and are ignored. #### Maximum profiles This caps the number of unique profiles processed in a run. Use a small number for testing and increase the limit after checking output quality. #### Recent posts to sample This controls how many recent public post edges are used for engagement calculations. Higher values can improve confidence when the profile data includes recent post edges. Private or restricted profiles may return zero sampled posts. #### Proxy mode Instagram can block anonymous data-center traffic. The recommended setting uses Apify Residential Proxy when available. You can disable proxy mode for local testing or when your own session cookie is enough. #### Optional Instagram session You can provide your own Instagram `sessionid` cookie if public requests are blocked. Use only accounts and cookies you are authorized to use. The cookie is marked secret in the input schema. ### Example input ```json { "usernames": ["instagram", "natgeo"], "profileUrls": [{ "url": "https://www.instagram.com/instagram/" }], "maxProfiles": 10, "maxRecentPosts": 12, "proxyGroup": "AUTO", "countryCode": "US" } ```` ### Example output ```json { "username": "instagram", "profileUrl": "https://www.instagram.com/instagram/", "status": "ok", "followers": 600000000, "following": 100, "postsCount": 8000, "recentPostsSampled": 12, "engagementRate": 0.0032, "botScore": 0.12, "riskLevel": "low", "confidence": 0.82, "reasonTags": ["verified_account", "established_post_history"], "sampledAt": "2026-06-20T12:00:00.000Z" } ``` ### How is the bot score calculated? The score is a transparent heuristic, not a legal or identity claim. The actor adds risk when it sees patterns that often deserve manual review. Examples include following far more accounts than follow back, very low engagement for a large audience, very few posts for a high follower count, or likes without comments. The actor reduces risk when it sees verified status, established post history, or healthy engagement. The exact reason tags are included so your team can decide whether the score makes sense for the profile. ### Confidence and limitations `confidence` measures how much evidence was available. Public profiles with followers, following, media count, and sampled posts usually receive higher confidence. Private profiles, unavailable profiles, and login-restricted responses receive lower confidence. Instagram changes access rules often, so some profiles may need a session cookie or may return an unavailable row. Use the actor as a screening tool, not as the only decision source. ### Tips for better results Run a small test batch first. Review profiles with `medium` or `high` risk manually. Use `reasonTags` to build your own review rules. Compare repeated runs over time for sudden follower or engagement changes. Keep `maxRecentPosts` at 12 for a balanced first audit. Use a session cookie only when you understand Instagram's terms and your own compliance requirements. ### Integrations Send the dataset to Google Sheets for quick influencer shortlists. Connect results to a CRM and mark high-risk creators for manual review. Trigger a webhook when a monitored creator crosses a risk threshold. Export CSV files for agency campaign planning. Combine the actor with other automation-lab Instagram actors when you need raw posts, comments, or media after the risk screen. ### API usage with Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/instagram-bot-detector').call({ usernames: ['instagram', 'natgeo'], maxProfiles: 10, maxRecentPosts: 12, }); console.log(run.defaultDatasetId); ``` ### API usage with Python ```python from apify_client import ApifyClient client = ApifyClient('MY-APIFY-TOKEN') run = client.actor('automation-lab/instagram-bot-detector').call(run_input={ 'usernames': ['instagram', 'natgeo'], 'maxProfiles': 10, 'maxRecentPosts': 12, }) print(run['defaultDatasetId']) ``` ### API usage with cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/automation-lab~instagram-bot-detector/runs?token=MY-APIFY-TOKEN' \ -H 'Content-Type: application/json' \ -d '{"usernames":["instagram","natgeo"],"maxProfiles":10,"maxRecentPosts":12}' ``` ### MCP usage Use this actor from Claude Desktop, Claude Code, or any MCP-compatible client through Apify MCP. MCP URL: `https://mcp.apify.com/?tools=automation-lab/instagram-bot-detector` Claude Code setup: ```bash claude mcp add apify-instagram-bot-detector https://mcp.apify.com/?tools=automation-lab/instagram-bot-detector ``` Claude Desktop JSON config: ```json { "mcpServers": { "apify-instagram-bot-detector": { "url": "https://mcp.apify.com/?tools=automation-lab/instagram-bot-detector" } } } ``` Example prompts: - "Audit these Instagram usernames for bot-risk signals and return high-risk profiles only." - "Run Instagram Bot Detector for this creator shortlist and summarize the reason tags." - "Compare the bot scores from this week's run with last week's exported dataset." ### Error handling If a profile cannot be fetched, the actor returns a dataset row with `status: unavailable` or `status: error`. This keeps bulk audits easy to reconcile because every requested profile can still appear in the export. Check `errorMessage` for profile-specific details. ### FAQ #### Can this prove that an account is a bot? No. It is a transparent risk screen for manual review, not a definitive identity judgment. #### Does it require login? Many public profiles work without a cookie when proxy access is available, but Instagram can require login for some requests. ### Troubleshooting #### Why did I get unavailable profiles? Instagram may require login, block a request, rate-limit traffic, or hide a private/suspended profile. Try a smaller batch, use Residential Proxy, or provide an authorized `sessionid` cookie. #### Why is `recentPostsSampled` zero? The profile may be private, Instagram may omit recent media edges, or the request may have been limited. The actor can still calculate ratio-based signals when follower/following data is available. #### Is a high bot score proof of fraud? No. A high score means the profile deserves manual review based on transparent public signals. Do not use the score as the sole basis for enforcement or contractual decisions. ### Legality and compliance This actor works with public profile information and optional user-provided access credentials. You are responsible for using the actor in compliance with Instagram's terms, privacy laws, and your organization's policies. Avoid collecting or processing personal data you do not need. Use the output for legitimate screening, analytics, and fraud-prevention workflows. ### Related scrapers - [Instagram Scraper](https://apify.com/automation-lab/instagram-scraper) - [Instagram Comments Scraper](https://apify.com/automation-lab/instagram-comments-scraper) - [Instagram Hashtag Scraper](https://apify.com/automation-lab/instagram-hashtag-scraper) - [Instagram Media Downloader](https://apify.com/automation-lab/instagram-media-downloader) - [Instagram Followers Count Bulk Scraper](https://apify.com/automation-lab/instagram-followers-count-bulk-scraper) ### Changelog Initial version audits bulk Instagram usernames and profile URLs with public-profile heuristics. ### Support If a profile consistently fails, include the username, run ID, and whether you used a session cookie when contacting support. ### Summary Instagram Bot Detector helps teams prioritize manual review by turning public Instagram profile signals into explainable risk rows. # Actor input Schema ## `usernames` (type: `array`): Instagram handles to audit. You can use plain usernames with or without @. ## `profileUrls` (type: `array`): Optional Instagram profile URLs to audit in addition to usernames. ## `maxProfiles` (type: `integer`): Maximum number of unique profiles to audit in this run. ## `maxRecentPosts` (type: `integer`): Number of recent public posts to use for engagement-rate and posting-frequency heuristics. Private/unavailable profiles may have zero sampled posts. ## `proxyGroup` (type: `string`): AUTO uses Apify Residential Proxy when available, which is usually required by Instagram. NONE disables proxy for testing. ## `countryCode` (type: `string`): Two-letter country code for the proxy exit location. ## `sessionCookie` (type: `string`): Optional sessionid cookie from your own logged-in Instagram account. Use only if public requests are blocked for your profiles. ## Actor input object example ```json { "usernames": [ "instagram", "natgeo" ], "profileUrls": [ { "url": "https://www.instagram.com/instagram/" } ], "maxProfiles": 10, "maxRecentPosts": 12, "proxyGroup": "AUTO", "countryCode": "US" } ``` # Actor output Schema ## `overview` (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 = { "usernames": [ "instagram", "natgeo" ], "profileUrls": [ { "url": "https://www.instagram.com/instagram/" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/instagram-bot-detector").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 = { "usernames": [ "instagram", "natgeo", ], "profileUrls": [{ "url": "https://www.instagram.com/instagram/" }], } # Run the Actor and wait for it to finish run = client.actor("automation-lab/instagram-bot-detector").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 '{ "usernames": [ "instagram", "natgeo" ], "profileUrls": [ { "url": "https://www.instagram.com/instagram/" } ] }' | apify call automation-lab/instagram-bot-detector --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/instagram-bot-detector", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Instagram Bot Detector", "description": "🤖 Audit Instagram profiles for fake-follower and bot-like risk with transparent scores, engagement signals, and reason tags.", "version": "0.1", "x-build-id": "cQ10EhEDYleKYV7q2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~instagram-bot-detector/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-instagram-bot-detector", "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/automation-lab~instagram-bot-detector/runs": { "post": { "operationId": "runs-sync-automation-lab-instagram-bot-detector", "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/automation-lab~instagram-bot-detector/run-sync": { "post": { "operationId": "run-sync-automation-lab-instagram-bot-detector", "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", "properties": { "usernames": { "title": "Instagram usernames", "type": "array", "description": "Instagram handles to audit. You can use plain usernames with or without @.", "items": { "type": "string" } }, "profileUrls": { "title": "Instagram profile URLs", "type": "array", "description": "Optional Instagram profile URLs to audit in addition to usernames.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxProfiles": { "title": "Maximum profiles", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of unique profiles to audit in this run.", "default": 10 }, "maxRecentPosts": { "title": "Recent posts to sample", "minimum": 0, "maximum": 24, "type": "integer", "description": "Number of recent public posts to use for engagement-rate and posting-frequency heuristics. Private/unavailable profiles may have zero sampled posts.", "default": 12 }, "proxyGroup": { "title": "Proxy mode", "enum": [ "AUTO", "RESIDENTIAL", "NONE" ], "type": "string", "description": "AUTO uses Apify Residential Proxy when available, which is usually required by Instagram. NONE disables proxy for testing.", "default": "AUTO" }, "countryCode": { "title": "Proxy country", "minLength": 2, "maxLength": 2, "type": "string", "description": "Two-letter country code for the proxy exit location.", "default": "US" }, "sessionCookie": { "title": "Instagram sessionid cookie", "type": "string", "description": "Optional sessionid cookie from your own logged-in Instagram account. Use only if public requests are blocked for your profiles." } } }, "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 } } } } } } } } } } ```