instagram-scraper

Instagram Scraper

Public Instagram data via Apify's Instagram Scraper. No Instagram login, no cookies, no Meta app review.

Setup — do this before any data call

Always run this preflight first. Do not attempt a data call until it passes.

if [ -n "$APIFY_TOKEN" ]; then
  echo "AUTH_OK curl"
elif command -v

The checks are ordered cheapest-first. The npx fallback costs about four seconds, so it only runs when an Apify config directory shows a previous login — a first-time user reaches AUTH_MISSING instantly rather than waiting for a package download that was never going to find a session.

$HOME and $USERPROFILE are both checked on purpose. On Windows they can point to different places — sandboxes and some CI images remap $HOME while the Apify CLI keeps writing to $USERPROFILE\.apify. Testing only $HOME there reports AUTH_MISSING for a user who is perfectly well logged in, and the skill would then send them to sign up for an account they already have. If you see AUTH_MISSING on a machine you believe is authenticated, check both paths before trusting it.

The two AUTH_OK modes are not interchangeable — the preflight tells you which call form to use.

• AUTH_OK curl — a token is in the environment. The HTTP calls in this skill work as written.
• AUTH_OK cli: <prefix> — the Apify CLI holds the session and the token is not readable from disk. ~/.apify/auth.json carries account metadata only (username, plan, proxy groups — no token field); current CLI versions keep the token in the OS secrets backend. Do not try to extract one from that file: a bogus Authorization: Bearer header returns 401 and looks exactly like a revoked token. Use apify call instead, prefixed with whatever the preflight printed after cli: (apify, or npx --yes apify-cli@latest when the CLI is not on PATH).

If the preflight prints AUTH_OK cli

Every payload in this skill still applies — write it to a file and hand it to apify call instead of curl:

• Always pass the Actor id explicitly. With no id, apify call runs the Actor defined by a local .actor/actor.json — inside an Actor repo that silently runs the wrong thing.
• Prefer --input-file over inline -i '{...}'. Inline JSON has to survive the shell, and PowerShell and cmd.exe mangle the quoting. A file never does. --input-file - reads stdin.
• --output-dataset prints the dataset to stdout — the same array run-sync-get-dataset-items returns, so every field in the Output section below is identical. --silent keeps run logs off stdout so the output parses as JSON.
• apify call waits for the run to finish, so the async polling pattern below is only needed on the curl path. Add --timeout <seconds> to bound a long job.
• The run is billed to whichever account the CLI is logged in as. apify info prints it — worth showing the user if they may have more than one.

If the preflight prints AUTH_MISSING

Open the Apify sign-up page in the user's browser, then ask for the token. Run this exactly as-is — it picks the right command per platform and degrades to printing the URL when there is no browser (CI, SSH, containers):

Then tell the user what is happening — but do not wait for a reply:

I've opened Apify's sign-up page in your browser. Instagram data comes through Apify, which is free to start — $5 of credits every month, no credit card, enough for around 2,000 results.

Sign up there (or log in, if you already have an account). I'm opening the authorisation step now too — approve it and this machine stays connected, so you won't have to do any of this again.

The sign-up link is a referral link.

Immediately run the login. Do not ask the user to confirm they've signed up first — this command opens Apify's authorisation page, which offers sign-up itself, and then blocks until the user finishes. The command is the wait, so there is nothing to detect and no round trip to burn:

• -m console is required. Bare apify login first prompts for a login method and will hang forever on stdin the agent cannot answer. -m console goes straight to the browser flow.
• timeout 300 bounds it, so an abandoned sign-up doesn't hang the session. Exit code 124 means it timed out — the user walked away, so ask whether they still want to continue rather than silently retrying.
• On success it prints "Success: You are logged in to Apify as <username>. Your token is stored in your OS keyring." From then on the preflight resolves to AUTH_OK cli in every future session — no token to paste, store, or leak into a transcript.

Then re-run the preflight. That is how you know whether it worked — not the message, and not an assumption that the browser step went fine:

The preflight's CLI branch is just apify info, which exits 0 when a session exists and non-zero when it doesn't. It is the same check that produced AUTH_MISSING a moment earlier, so re-running it is a genuine confirmation rather than a restatement of what you already believed.

Two failure modes worth naming, because both look like success from the outside: the user closes the authorisation tab without approving (exit 124 at the timeout), and the user signs up but never reaches the approval step. In both the sign-up may well have succeeded while this machine is still not connected — which is exactly why the preflight, not the sign-up, is the thing to trust.

Keep the sign-up tab and the login in that order. The sign-up page is where the referral is recorded; the authorisation step afterwards is just this machine connecting to whichever account now exists. Opening them the other way round loses the attribution.

Never ask the user for their token

Do not request, accept, or handle an Apify API token in the conversation. The browser login above exists precisely so the secret never reaches the agent: the CLI receives it directly from Apify and writes it to the OS keyring, and this skill only ever reads the result of that (apify info's exit code), never the value.

If the user offers a token unprompted, decline it and point them at one of the two safe routes below. Anything pasted into a session is a live credential sitting in a transcript, in scrollback, and in any log that captures the conversation.

Headless environments — CI, SSH, containers, anywhere the OAuth round trip cannot open a browser. The user sets the credential themselves, out of band, before starting the agent:

The preflight then reports AUTH_OK curl and everything works, with the value never passing through the conversation.

Or the CLI's own prompt, which reads the token from stdin rather than the conversation:

Avoid login -t <token>. Passing a secret as a command-line argument exposes it in the process list to every other process on the machine, and in shell history. It also clears the stored session before validating, so a typo or a stale value logs the user out of a session that was working.

When a token does legitimately exist in the environment, always reference it as $APIFY_TOKEN and let the shell expand it — as every example in this skill does. Never substitute the literal value into a command, a log line, or a message.

Fetching data

One call, synchronous, returns the items directly. Good for anything that finishes inside ~60 s. This is the AUTH_OK curl form — under AUTH_OK cli, put the same -d payload in a file and run it through apify call as shown above.

The User-Agent header is only so runs originating from this skill can be told apart in logs. It carries no personal data and can be removed.

Choosing resultsType

Pick details whenever the user only needs profile numbers. Using posts for that question costs up to 100× more for no benefit.

Input reference

Four more fields work but are not in the published input schema. They are documented in the Actor's README and verified working — use them freely:

URL handling

directUrls is more forgiving than it looks. All of these are accepted:

• Profile IDs work anywhere a profile URL does — a bare numeric ID is fine
• instagram.com/_u/natgeo/profilecard/ — _u and profilecard are stripped
• instagram.com/stories/username/ — reduced to the username
• instagram.com/share/BAC6cDeb_- — resolved to the canonical post URL
• instagram.com/explore/locations/7538318/ — the ID alone is valid, no slug needed

Not supported: numeric post IDs in URL form (instagram.com/p/3369450800358839406/) for posts, reels, mentions or details. Use the shortCode form instead. This format does work for comments.

The URL type drives the output schema. Hashtag, location, audio and explore URLs return their own metadata even when paired with another content mode — so a location URL with resultsType: "details" yields place details, not profile details.

Constraints that will bite you

• One content type per run. There is no way to get posts and comments in a single call. Run twice.
• URLs beat search. directUrls and search cannot be combined; if both are present the URLs win and the search is ignored.
• Hashtags go in as plaintext — travel, never #travel.
• Multiple search terms are comma-separated in one string: "travel, fitness".
• Free plans get about one page of comments per post (~15). Paid plans have no such cap. Do not report this as an error — say what it is.

Common tasks

Every capability the Actor exposes, with the payload for each. Swap the -d '...' into the curl above.

Profile stats for several accounts — cheapest possible call:

A profile's recent posts, last 30 days:

A profile's reels:

A profile's current stories — only returns anything while stories are live, and often needs a paid plan:

Posts that mention an account — brand monitoring:

Comments on one post:

Posts under a hashtag:

Find accounts by keyword — user returns account records:

Search profiles by name — profile matches on profile pages:

Posts from a place:

Posts from a specific location or hashtag URL — pass the URL directly instead of searching:

Tracking which query produced which post — when scraping several hashtags or profiles in one run, addParentData stamps each item with its source so the results can be grouped afterwards:

Deep profile statistics — account type, post and reel counts, category, city, public contact fields. Also works on private profiles:

Recent posts, excluding pinned ones:

Only the pinned posts — invert the same pair:

Newest comments first, including replies — both paid-plan only:

Output

Each content type produces a different schema, and they cannot be combined in one run. Samples below are abridged to the useful fields; the URL type you pass can override the shape (a location URL returns place data even under another mode).

Post / carousel (resultsType: "posts") — 23 fields:

Reel (resultsType: "reels") — 31 fields. Posts plus video:

Comment (resultsType: "comments"):

repliesCount and replies populate only with includeNestedComments: true (paid).

Profile details (resultsType: "details") — 22 fields. Verified live:

details already includes latestPosts (up to 12) and relatedProfiles (up to 48) at no extra cost. If the user wants a profile's numbers and a look at recent posts, one details call covers both — a second posts call is usually waste.

With addProfileStatistics: true a statistics object is appended (~60 fields): account_type (1 Personal, 2 Business, 3 Creator), media_count, total_clips_count, category, city_name, address_street, zip, bio_links, mutual_followers_count.

Mentions (resultsType: "mentions") — 21 fields, post-shaped, plus taggedUsers, music, carouselImages, carouselImageCount.

Place details (location URL) — 16 fields:

Hashtag details (hashtag URL) — 15 fields, including SEO-style extras: name, postsCount, url, id, posts, postsPerDay, difficulty, related, frequent, average, rare, relatedFrequent, relatedAverage, relatedRare.

Search results carry searchTerm and searchSource so you can tell which query produced each row:

• Hashtag search — 6 fields: searchTerm, searchSource, name, postsCount, url, id
• Place search — 17 fields: place-details shape plus searchTerm / searchSource
• Profile search — 13 fields: post-shaped, with ownerUsername, ownerFullName, taggedUsers

Images are URLs, not files

Every image and video field is a link to Instagram's CDN. Nothing is downloaded, and those links are signed and expire after a few hours. If the user needs the media itself, fetch it promptly on their own bandwidth.

Runs longer than a minute

For large jobs, start async and poll rather than holding a sync connection:

Poll until status is SUCCEEDED, then fetch items. FAILED or ABORTED means stop and report — do not silently retry a job the user is paying for.

Errors

An empty result is a real answer. Private accounts, deleted posts and quiet hashtags all legitimately return nothing.

Data quirks to report accurately, not treat as bugs

• likesCount: -1 means the creator hid the like count. Instagram does not expose it. Say "hidden by the creator" — never report it as zero or as an error.
• Private profiles generally return nothing. One exception: if a private account is tagged as a collaborator on a post and any co-author is public, Instagram treats that post as public and it will appear in results.
• Metrics can differ from what the app shows. Instagram serves slightly different counts to logged-out visitors, and large counts move constantly. Small discrepancies are expected.
• Result counts are not guaranteed. There is no fixed cap; you get what Instagram exposes publicly. To sanity-check what should be available, open the URL in an incognito window.

Cost discipline

The user is paying per result. Treat that as real money.

• Always set resultsLimit. The default is 100 per URL; a five-URL call with the default costs 500 results when the user probably wanted 25.
• Use resultsType: "details" for any question about followers, bio or post counts. It returns one result per profile.
• Start small. For anything open-ended, run a bounded first pass, show the user what came back, and confirm before scaling up.
• Say what a large run will cost before starting it. At $2.30/1,000, a 5,000-result job is about $11.50.
• Never loop the same call after a 401 or 402 — each attempt can be billable and none of them will succeed.