Public API

igscraper REST API

Automate Instagram scraping with the igscraper REST API. All endpoints use /api/v1 with Bearer token authentication. Submit a job, poll for status, fetch results.

Authentication

All requests require a Bearer token.

Authorization: Bearer YOUR_API_KEY

POST requests must include Content-Type: application/json. Get your key from the API dashboard.

Quickstart

Submit Job

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-per-job" \
  -d '{
    "external_user_id": "customer-123",
    "tool_type": "followers",
    "params": {
      "usernames": ["nasa"],
      "max_followers": 50
    }
  }'

We use cookies

By clicking "Accept", you consent to cookies. Cookies Policy.We use cookies and similar technologies to provide, protect, and improve our services. Functional cookies (like referral attribution) are always on. By clicking "Accept", you consent to our use of analytics and marketing cookies. You can learn more about how we use cookies and manage your preferences in our Cookies Policy.

Poll Job Status

curl "https://igscraper.co/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

Response: 200 OK (processing)

{
  "job_id": "4d83c31f-ef37-4fa2-ad3e-07bbd15e9936",
  "external_user_id": "customer-123",
  "namespace": "team-acme",
  "status": "PROCESSING",
  "created_at": "2026-03-17T17:30:00.000Z",
  "updated_at": "2026-03-17T17:30:05.000Z",
  "completed_at": null,
  "progress_percent": 45,
  "number_of_results": 0,
  "cost_charged": 0,
  "tool_type": "followers"
}

Response: 200 OK (completed)

{
  "job_id": "4d83c31f-ef37-4fa2-ad3e-07bbd15e9936",
  "external_user_id": "customer-123",
  "namespace": "team-acme",
  "status": "COMPLETED",
  "created_at": "2026-03-17T17:30:00.000Z",
  "updated_at": "2026-03-17T17:30:12.000Z",
  "completed_at": "2026-03-17T17:30:12.000Z",
  "progress_percent": 100,
  "number_of_results": 50,
  "cost_charged": 250,
  "tool_type": "followers"
}

Poll until status is COMPLETED. 2s interval recommended.

Fetch Results

curl "https://igscraper.co/api/v1/jobs/$JOB_ID/results?page=1&limit=50" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

Response: 200 OK

{
  "job_id": "4d83c31f-ef37-4fa2-ad3e-07bbd15e9936",
  "external_user_id": "customer-123",
  "status": "COMPLETED",
  "columns": [
    "source",
    "type",
    "user_id",
    "username",
    "full_name",
    "verified",
    "private"
  ],
  "data": [
    {
      "source": "nasa",
      "type": "follower",
      "user_id": "12345678",
      "username": "space_fan_01",
      "full_name": "Alex Johnson",
      "verified": "false",
      "private": "false"
    }
  ],
  "messages": [],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 50,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Or Download CSV

curl -L "https://igscraper.co/api/v1/jobs/$JOB_ID/download" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -o results.csv

Returns 409 while the job is still running.

Job Statuses

Status	Description
`QUEUED`	Job accepted, waiting to start.
`PROCESSING`	Actively scraping.
`COMPLETED`	Results ready.
`FAILED`	Error encountered.
`CANCELLED`	Job was cancelled.

external_user_id

Stable end-user identifier (1-255 chars). Deduplication and rate limits are scoped per API key project + this field.

Idempotency Keys

Unique key per new job (UUID recommended).
Reuse the same key to safely retry the same payload.
Mismatched payload with same key returns 409.

Credits

Charged on completion. Cost depends on tool type and delivered rows. See pricing.

Listing Jobs (Cursor Pagination)

Use cursor_pagination.next_cursor from each response. Do not send page and cursor together.

curl "https://igscraper.co/api/v1/jobs?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

Tool Reference

Select a tool to see its parameters, example request, and result columns.

Tool Type Aliases

Use canonical tool_type values in production. Compatibility aliases are accepted and normalized server-side as shown below.

Alias	Canonical tool_type
`email`	`emails`
`phone`	`phones`
`hashtags`	`hashtag`
`hashtag-research`	`hashtag`
`locations`	`location`
`location-scraper`	`location`
`post-likers`	`single-post-likers`
`single-post-liker`	`single-post-likers`
`commenter`	`commenters`
`post-commenters`	`single-post-commenters`
`single-post-commenter`	`single-post-commenters`
`post-scrapers`	`post-scraper`
`single-post-scrapers`	`single-post-scraper`

Followers

Extract follower profiles for one or more usernames.

Parameters

usernamesstring[]

required

· 1-10 items, 1-30 chars each

Instagram usernames (letters, numbers, dot, underscore).

max_followersintegerdefault: 50· 1-10,000

Maximum followers to extract per username.

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on delivered rows.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-followers-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "followers",
  "params": {
    "usernames": [
      "nasa"
    ],
    "max_followers": 50
  }
}'

Base Result Columns

sourcetypeuser_idusernamefull_nameverifiedprivateprofile_pic_url

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.

Following

Extract following profiles for one or more usernames.

Parameters

usernamesstring[]

required

· 1-10 items, 1-30 chars each

Instagram usernames (letters, numbers, dot, underscore).

max_followingintegerdefault: 50· 1-10,000

Maximum following to extract per username.

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on delivered rows.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-following-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "following",
  "params": {
    "usernames": [
      "nasa"
    ],
    "max_following": 50
  }
}'

Base Result Columns

sourcetypeuser_idusernamefull_nameverifiedprivateprofile_pic_url

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.

Likers [Profile]

Find likers from recent posts of target usernames.

Parameters

usernamesstring[]

required

· 1-10 items, 1-30 chars each

Usernames whose posts should be scanned.

max_postsintegerdefault: 12· 1-50

Maximum posts to scan per username.

max_new_postsintegerdefault: 2· 1-12

Prioritize this many newest posts first.

max_total_likersintegerdefault: 0· 0-10,000

Total liker cap (0 means dynamic, no fixed cap).

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on delivered rows.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-likers-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "likers",
  "params": {
    "usernames": [
      "nasa"
    ],
    "max_posts": 12,
    "max_new_posts": 2,
    "max_total_likers": 0
  }
}'

Base Result Columns

sourcetypeuser_idusernamefull_nameverifiedprivateprofile_pic_url

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.

Emails

Extract emails from followers, likers, or hashtag posters.

Parameters

email_source_typestringdefault: followers· followers | likers | hashtag_posters

Select source strategy for candidate profiles.

usernamesstring[]

conditional

default: []· up to 10 items, 1-30 chars each

Required when source type is followers or likers.

hashtagstring

conditional

· 1-50 chars, letters/numbers/_

Required when source type is hashtag_posters.

max_emailsintegerdefault: 1000· 1-1,000

Maximum email results to return per target. Total across usernames cannot exceed max_emails_per_job (default 1,000).

max_followersintegerdefault: 50· 1-10,000

Follower scan cap for follower-based collection.

max_postsintegerdefault: 12· 1-50

Maximum posts scanned for liker-based collection.

max_new_postsintegerdefault: 2· 1-12

Prioritize this many newest posts first.

max_total_likersintegerdefault: 0· 0-10,000

Total liker cap (0 means dynamic, no fixed cap).

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-emails-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "emails",
  "params": {
    "email_source_type": "followers",
    "usernames": [
      "nasa"
    ],
    "max_emails": 300,
    "max_followers": 50,
    "max_posts": 12,
    "max_new_posts": 2,
    "max_total_likers": 0
  }
}'

Base Result Columns

sourcetypeuser_idusernamefull_nameprofile_pic_urlbiographyemailfollower_countmedia_countfollowing_countaccount_typebusiness_category_namecategory_namecategorycity_namewebsitebusinessverifiedprivate

Conditional Appended Columns

When enrich_country_date=true, the result appends country, date.

Phones

Extract phone numbers from followers, likers, or hashtag posters.

Parameters

phone_source_typestringdefault: followers· followers | likers | hashtag_posters

Select source strategy for candidate profiles.

usernamesstring[]

conditional

default: []· up to 10 items, 1-30 chars each

Required when source type is followers or likers.

hashtagstring

conditional

· 1-50 chars, letters/numbers/_

Required when source type is hashtag_posters.

max_phonesintegerdefault: 1000· 1-1,000

Maximum phone results to return per target. Total across usernames cannot exceed max_phones_per_job (default 1,000).

max_followersintegerdefault: 50· 1-10,000

Follower scan cap for follower-based collection.

max_postsintegerdefault: 12· 1-50

Maximum posts scanned for liker-based collection.

max_new_postsintegerdefault: 2· 1-12

Prioritize this many newest posts first.

max_total_likersintegerdefault: 0· 0-10,000

Total liker cap (0 means dynamic, no fixed cap).

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-phones-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "phones",
  "params": {
    "phone_source_type": "followers",
    "usernames": [
      "nasa"
    ],
    "max_phones": 300,
    "max_followers": 50,
    "max_posts": 12,
    "max_new_posts": 2,
    "max_total_likers": 0
  }
}'

Base Result Columns

sourcetypeuser_idusernamefull_nameprofile_pic_urlbiographyphonefollower_countmedia_countfollowing_countaccount_typebusiness_category_namecategory_namecategorycity_namewebsitebusinessverifiedprivate

Conditional Appended Columns

When enrich_country_date=true, the result appends country, date.

Hashtag

Discover profiles from hashtag content.

Parameters

hashtagstring

required

· 1-50 chars, letters/numbers/_

Hashtag without #.

hashtag_content_typestringdefault: recent· recent | top

Which feed to inspect.

hashtag_scrape_typestringdefault: posters· posters | likers

Return post owners or post likers.

max_resultsintegerdefault: 100· 1-1,000

Maximum profiles to return.

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on delivered rows.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-hashtag-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "hashtag",
  "params": {
    "hashtag": "fitness",
    "hashtag_content_type": "recent",
    "hashtag_scrape_type": "posters",
    "max_results": 100
  }
}'

Base Result Columns

sourcetypecontentuser_idusernamefull_nameverifiedprivateprofile_pic_url

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.

Location

Discover profiles from Instagram location feeds.

Parameters

location_idstring

required

· numeric string

Instagram location id (digits only).

location_querystring· 1-200 chars

Human-readable location label for your own reference.

location_content_typestringdefault: recent· recent | top

Which feed to inspect.

location_scrape_typestringdefault: posters· posters | likers

Return post owners or post likers.

max_resultsintegerdefault: 100· 1-1,000

Maximum profiles to return.

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on delivered rows.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-location-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "location",
  "params": {
    "location_id": "213385402",
    "location_query": "miami",
    "location_content_type": "recent",
    "location_scrape_type": "posters",
    "max_results": 100
  }
}'

Base Result Columns

sourcetypecontentuser_idusernamefull_nameverifiedprivateprofile_pic_url

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.

Likers [Post URL]

Extract likers from one Instagram post URL.

Parameters

post_urlstring

required

· Instagram post URL (/p/ or /reel/)

Instagram post URL on instagram.com or www.instagram.com. Lookalike domains are rejected with 400. The API canonicalizes accepted input to https://www.instagram.com/p/<post_id>/.

max_resultsintegerdefault: 100· 1-1,000

Maximum liker profiles to return.

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on delivered rows.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-single-post-likers-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "single-post-likers",
  "params": {
    "post_url": "https://www.instagram.com/p/ABC123/",
    "max_results": 100
  }
}'

Base Result Columns

sourcetypeuser_idusernamefull_nameverifiedprivateprofile_pic_url

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.

Commenters [Profile]

Extract unique commenters from recent posts of target usernames.

Parameters

usernamesstring[]

required

· 1-10 items, 1-30 chars each

Usernames whose post comments should be scanned. One leading @ is accepted and stripped before validation.

max_postsintegerdefault: 12· 1-50

Maximum posts to scan per username.

max_new_postsintegerdefault: 2· 1-12

Prioritize this many newest posts first.

max_resultsintegerdefault: 100· 1-1,000

Maximum unique commenters to return per target. Total across unique usernames cannot exceed 1,000.

include_repliesbooleandefault: false· true | false

Include reply comments in addition to top-level comments.

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on delivered rows.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-commenters-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "commenters",
  "params": {
    "usernames": [
      "nasa"
    ],
    "max_posts": 12,
    "max_new_posts": 2,
    "max_results": 100,
    "include_replies": false
  }
}'

Base Result Columns

sourcesource_typemedia_idpost_urlcommenter_usernamecommenter_user_idfull_nameverifiedprivateprofile_pic_urlcomment_texts_jsoninclude_replies

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.

Commenters [Post URL]

Extract unique commenters from one Instagram post URL.

Parameters

post_urlstring

required

· Instagram post URL (/p/ or /reel/)

Instagram post URL on instagram.com or www.instagram.com. Lookalike domains are rejected with 400. The API canonicalizes accepted input to https://www.instagram.com/p/<post_id>/.

max_resultsintegerdefault: 100· 1-1,000

Maximum unique commenters to return.

include_repliesbooleandefault: false· true | false

Include reply comments in addition to top-level comments.

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on delivered rows.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on delivered rows. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-single-post-commenters-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "single-post-commenters",
  "params": {
    "post_url": "https://www.instagram.com/p/ABC123/",
    "max_results": 100,
    "include_replies": false
  }
}'

Base Result Columns

sourcesource_typemedia_idpost_urlcommenter_usernamecommenter_user_idfull_nameverifiedprivateprofile_pic_urlcomment_texts_jsoninclude_replies

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.

Posts [Feed]

Extract post-level data from profile feeds or hashtag feeds.

Parameters

source_typestring· profile | hashtag

Optional explicit mode. If omitted: hashtag only -> hashtag mode; usernames only -> profile mode; both hashtag and usernames -> rejected as ambiguous. Mixed explicit payloads are rejected.

usernamesstring[]

conditional

default: []· 1-10 items, 1-30 chars each

Required when source_type=profile. One leading @ is accepted and stripped before validation.

hashtagstring

conditional

· 1-50 chars, letters/numbers/_

Required when source_type=hashtag.

hashtag_content_typestringdefault: recent· recent | top

Used in hashtag mode.

max_postsintegerdefault: 100· 1-1,000

Maximum posts to return per target in profile mode, or for the single hashtag target in hashtag mode. Profile-mode totals across unique usernames cannot exceed 1,000.

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on post owners.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on post owners. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-post-scraper-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "post-scraper",
  "params": {
    "source_type": "profile",
    "usernames": [
      "nasa"
    ],
    "max_posts": 100
  }
}'

Base Result Columns

sourcesource_typesource_refmedia_idpost_urlshortcodemedia_typeproduct_typecaptionusernameuser_idtaken_at_isomedia_urls_jsonraw_post_json

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.
raw_post_json is curated and always includes: source, source_type, source_ref, media_id, post_url, shortcode, media_type, product_type, caption, taken_at_iso, media_urls_json, user_id, username, full_name, profile_pic_url, verified, private.
raw_post_json adds biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website when profile enrichment is present, and country, date when country/date enrichment is present.

Posts [Post URL]

Extract normalized post-level data from one Instagram post URL.

Parameters

post_urlstring

required

· Instagram post URL (/p/ or /reel/)

Instagram post URL on instagram.com or www.instagram.com. Lookalike domains are rejected with 400. The API canonicalizes accepted input to https://www.instagram.com/p/<post_id>/.

enrich_profilesbooleandefault: false· true | false

Enable optional profile enrichment on the post owner.

enrich_country_datebooleandefault: false· true | false

Enable optional country/date add-on on the post owner. date is normalized to MM-YYYY (or empty when unparseable).

Submit Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-single-post-scraper-job" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "single-post-scraper",
  "params": {
    "post_url": "https://www.instagram.com/p/ABC123/"
  }
}'

Base Result Columns

sourcesource_typesource_refmedia_idpost_urlshortcodemedia_typeproduct_typecaptionusernameuser_idtaken_at_isomedia_urls_jsonraw_post_json

Conditional Appended Columns

When enrich_profiles=true, the result appends biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website.
When enrich_country_date=true, the result appends country, date.
raw_post_json is curated and always includes: source, source_type, source_ref, media_id, post_url, shortcode, media_type, product_type, caption, taken_at_iso, media_urls_json, user_id, username, full_name, profile_pic_url, verified, private.
raw_post_json adds biography, email, phone, follower_count, media_count, following_count, account_type, business, business_category_name, category_name, category, city_name, website when profile enrichment is present, and country, date when country/date enrichment is present.

Enrichment

At Submit Time

Add enrichment flags to any job submission. Both flags can be used independently or together.

Flag	Effect	Supported Tools
`enrich_profiles`	Appends profile fields (bio, follower/following counts, category, etc.)	All except `emails`, `phones`
`enrich_country_date`	Appends `country` and `date` (MM-YYYY)	All tools

profile_pic_url is always included in base results and is not part of enrichment.

Retroactive Enrichment Flow

Enrich results of an already-completed job using the /enrich endpoint.

Submit one tool job at a time.
A completed job can be upgraded with add-ons it doesn't already have.
Preflight (GET .../enrich) shows eligibility and credit cost before starting.
Results and CSV download return 409 while enrichment is processing.
If the upgrade is already in progress or complete, returns 202/200 with replayed: true.
Credits are charged for retroactive enrichment.

Retroactive Enrichment Steps

1. Preflight

Check eligibility and credit reservation before starting.

curl "https://igscraper.co/api/v1/jobs/$JOB_ID/enrich?enrich_profiles=true&enrich_country_date=true" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

2. Start Upgrade

Start the upgrade with selected add-ons.

curl -X POST "https://igscraper.co/api/v1/jobs/$JOB_ID/enrich" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enrich_profiles": true,
    "enrich_country_date": true
  }'

3. Poll Upgrade Status

Poll until upgrade_status is no longer queued or processing.

curl "https://igscraper.co/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

Endpoints

Jobs

Submit jobs and read job status/results.

get

/api/v1/jobsList jobs

List jobs in your namespace. Supports offset pagination (page + limit) and cursor pagination (cursor + limit). page and cursor cannot be used together. Optional filters: status, external_user_id.

Security

bearerAuth

Request Example

curl -X GET "https://igscraper.co/api/v1/jobs?page=1&limit=50" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

Parameters

Name	In	Type	Required	Description	Rules
`page`	query	integer	No	Offset pagination page number.	minimum: 1 \| default: 1
`limit`	query	integer	No	Page size for list and results rows.	minimum: 1 \| maximum: 200 \| default: 50
`cursor`	query	string	No	Cursor token returned in cursor_pagination.next_cursor. Cannot be used together with page.	minLength: 1 \| maxLength: 1024
`status`	query	string	No	Filter jobs by one or more statuses. Comma-separated values are accepted (for example: COMPLETED,FAILED).

Request Body

No request body.

post

/api/v1/jobsSubmit a job

Submit a scraping job for one external user in your API key namespace.

Security

bearerAuth

Request Example

curl -X POST "https://igscraper.co/api/v1/jobs" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_user_id": "customer-123",
  "tool_type": "followers",
  "params": {
    "usernames": [
      "nasa"
    ],
    "max_followers": 50
  }
}'

Parameters

Name

get

/api/v1/jobs/{job_id}Get job

Get one job by id within your namespace.

Security

bearerAuth

Request Example

curl -X GET "https://igscraper.co/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

Parameters

Name	In	Type	Required	Description

get

/api/v1/jobs/{job_id}/downloadDownload job results (CSV)

Download the full CSV artifact for a completed job.

Security

bearerAuth

Request Example

curl -X GET "https://igscraper.co/api/v1/jobs/$JOB_ID/download" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

Parameters

Name	In	Type	Required

get

/api/v1/jobs/{job_id}/enrichGet enrichment preflight

Get retroactive enrichment eligibility and reservation preview for a completed job. When both add-ons are omitted or false, returns eligible=false with reason_code NO_ADDON_SELECTED.

Security

bearerAuth

Request Example

curl -X GET "https://igscraper.co/api/v1/jobs/$JOB_ID/enrich?enrich_profiles=false&enrich_country_date=false" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

Parameters

Name	In	Type

post

/api/v1/jobs/{job_id}/enrichStart enrichment upgrade

Start a retroactive enrichment upgrade for a completed job. Partially enriched jobs can request missing supported add-ons. Emails and phones support retroactive country/date only. At least one add-on must be selected. When request-body add-on flags are provided, they must be JSON booleans.

Security

bearerAuth

Request Example

curl -X POST "https://igscraper.co/api/v1/jobs/$JOB_ID/enrich" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enrich_profiles": false,
  "enrich_country_date": false
}'

Parameters

Name

get

/api/v1/jobs/{job_id}/resultsGet job results (JSON)

Read paginated JSON rows from a completed job result file.

Security

bearerAuth

Request Example

curl -X GET "https://igscraper.co/api/v1/jobs/$JOB_ID/results?page=1&limit=50" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

Parameters

Name	In	Type	Required

Rate Limits

Scope	Limit
Requests per minute	60
Requests per hour	1000
Job submissions per account per hour	120
Job submissions per external_user_id	12/hour and 5/minute burst

Showing default limits. Sign in to view your account-specific limits.

On 429, check Retry-After and retry with exponential backoff + jitter.

Errors

Code	Name	Cause	What To Do
`400`	Bad Request	Invalid or missing parameters.	Check the error message to see which field failed validation.
`401`	Unauthorized	Missing or invalid API key.	Verify your API key in /developers/api.
`402`	Payment Required	Not enough credits for the requested job.	Top up credits or reduce max_* parameters.
`403`	Forbidden	The external_user_id is blocked in your namespace, or the API owner account is phone-gated.	Unblock the external_user_id, or complete phone verification for the owner account.
`404`	Not Found	Job ID does not exist in your namespace.	Verify the job_id from your submit response.
`409`	Conflict	Idempotency mismatch, or results requested before completion.	Use a new idempotency key, or wait for status COMPLETED.
`413`	Payload Too Large	Request body exceeds size limit.	Reduce request size (for example fewer usernames).
`415`	Unsupported Media Type	Missing or incorrect Content-Type header.	Send Content-Type: application/json for POST requests.
`429`	Too Many Requests	Rate limit exceeded.	Wait for Retry-After seconds, then retry with backoff + jitter.
`500`	Internal Server Error	Unexpected server-side error.	Retry after a short delay. Contact support if it persists.
`503`	Service Unavailable	Temporary service issue.	Retry after a short delay with backoff + jitter.

Do not retry 400, 402, 403, or 409 without changing your request.

4. Fetch Enriched Results

Use the same results or download endpoints.

curl "https://igscraper.co/api/v1/jobs/$JOB_ID/results?page=1&limit=50" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY"

curl -L "https://igscraper.co/api/v1/jobs/$JOB_ID/download" \
  -H "Authorization: Bearer $IGSCRAPER_API_KEY" \
  -o results.csv

Request Body

application/json

Schema: JobSubmitRequest (oneOf)

Schema Variants

Choose variant by tool_type.

Variant

followers(tool_type=followers)

Followers extraction job.

Field	Type	Required	Description	Rules
`external_user_id`	string	Yes	Your stable customer/user ID from your system (for example: customer-123). Control characters are not allowed.	pattern: ^[^\u0000-\u001F\u007F]+$ \| minLength: 1 \| maxLength: 255
`tool_type`	string	Yes	-	const: followers

Request payload for creating a job. Select a variant by canonical tool_type. Compatibility aliases are accepted and normalized server-side (for example: email->emails, phone->phones, post-commenters->single-post-commenters, post-likers->single-post-likers, hashtag-research->hashtag, location-scraper->location).

Request Body

application/json

Schema: object

Field	Type	Required	Description	Rules
`enrich_profiles`	boolean	No	Select the profile-fields add-on for retroactive enrichment. It adds fields such as biography, email, phone, website, and business.	default: false
`enrich_country_date`	boolean	No	Select the country/date add-on for retroactive enrichment.	default: false

`job_id`	path	string	Yes	Job id returned by POST /api/v1/jobs.	-
`enrich_profiles`	query	boolean	No	Select the profile-fields add-on for retroactive enrichment. It adds fields such as biography, email, phone, website, and business. Accepted query values: true/false/1/0; invalid values are treated as omitted.	default: false
`enrich_country_date`	query	boolean	No	Select the country/date add-on for retroactive enrichment. Accepted query values: true/false/1/0; invalid values are treated as omitted.	default: false