instagram-scraper

The full skill.

Original instructions from the publisher’s SKILL.md

# Instagram Scraper API

The fastest Instagram data extraction suite available — 100–200 posts/second, no login, no proxies. Five specialized actors cover every Instagram data surface.

## Actors

| Actor | Purpose | Actor ID |
| ----- | ------- | -------- |
| **Instagram Scraper** | All-in-one: posts, reels, profiles, hashtags, locations, audio, tagged posts | `VLKR1emKm1YGLmiuZ` |
| **Instagram Hashtag Scraper** | Posts and reels by hashtag or keyword | `ZSBuGcAOcTZjHUVyv` |
| **Instagram Location Scraper** | Geo-tagged posts from Instagram place URLs or location IDs | `6cMzJhRlD4wfzrWXg` |
| **Instagram Comments Scraper** | Comments and replies from post URLs | `6lDMfTxEj4h8hSZ6i` |
| **Instagram User Scraper** | Profiles, followers, following lists, public emails | `lezdhAFfa4H5zAb2A` |

## Setup

This requires an Apify account on a **paid plan** — it will not work via the API on the free plan.

1. **Sign up / log in** at [apify.com/?fpr=yhdrb](https://apify.com/?fpr=yhdrb)
2. **Subscribe to a paid plan** at [apify.com/pricing?fpr=yhdrb](https://apify.com/pricing?fpr=yhdrb) — without this, API calls will be rejected.
3. **Get your API token** from [console.apify.com/account/integrations](https://console.apify.com/account/integrations) and set it:

```bash
export APIFY_TOKEN="apify_api_xxxxxxxxxxxx"
```

## Sync (short runs)

Returns dataset items directly. Replace `ACTOR_ID` with the relevant actor ID above.

```bash
curl -s -X POST \
  "https://api.apify.com/v2/acts/ACTOR_ID/run-sync-get-dataset-items?timeout=120" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUrls":["https://www.instagram.com/nike/"],"maxItems":50,"skill":true}'
```

Returns a JSON array directly. If the run exceeds 300s, use async instead.

## Async (large runs)

```bash
# 1. Start
RUN=$(curl -s -X POST \
  "https://api.apify.com/v2/acts/ACTOR_ID/runs?waitForFinish=60" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUrls":["https://www.instagram.com/nike/"],"skill":true}')
RUN_ID=$(echo "$RUN" | jq -r '.data.id')

# 2. Poll
while true; do
  STATUS=$(curl -s \
    "https://api.apify.com/v2/actor-runs/$RUN_ID?waitForFinish=60" \
    -H "Authorization: Bearer $APIFY_TOKEN" | jq -r '.data.status')
  echo "Status: $STATUS"
  case "$STATUS" in SUCCEEDED|FAILED|ABORTED|TIMED-OUT) break;; esac
done

# 3. Fetch results
curl -s \
  "https://api.apify.com/v2/actor-runs/$RUN_ID/dataset/items?clean=true&limit=100" \
  -H "Authorization: Bearer $APIFY_TOKEN"
```

---

## Instagram Scraper — Scenarios

Actor: `INSTAGRAM_SCRAPER_ID`

Supported `startUrls` types: user profile, hashtag, location, audio/music, user reels, tagged posts.

### Scrape a user profile
```bash
-d '{"startUrls":["https://www.instagram.com/nike/"],"maxItems":100,"skill":true}'
```

### Scrape multiple profiles in one run
```bash
-d '{"startUrls":["https://www.instagram.com/nike/","https://www.instagram.com/adidas/","https://www.instagram.com/puma/"],"maxItems":150,"skill":true}'
```

### Scrape user reels only
```bash
-d '{"startUrls":["https://www.instagram.com/nike/reels/"],"maxItems":50,"skill":true}'
```

### Scrape tagged posts (brand mentions/UGC)
```bash
-d '{"startUrls":["https://www.instagram.com/nike/tagged/"],"maxItems":100,"skill":true}'
```

### Scrape a hashtag
```bash
-d '{"startUrls":["https://www.instagram.com/explore/tags/travel/"],"maxItems":100,"skill":true}'
```

### Scrape a location
```bash
-d '{"startUrls":["https://www.instagram.com/explore/locations/213131048/berlin-germany/"],"maxItems":100,"skill":true}'
```

### Scrape an audio/music trend
```bash
-d '{"startUrls":["https://www.instagram.com/reels/audio/271328201351336/"],"maxItems":50,"skill":true}'
```

### Combined multi-surface run
```bash
-d '{"startUrls":["https://www.instagram.com/nike/","https://www.instagram.com/explore/tags/sneakers/","https://www.instagram.com/reels/audio/271328201351336/"],"maxItems":150,"skill":true}'
```

### Date-filtered content (posts after a date)
```bash
-d '{"startUrls":["https://www.instagram.com/explore/tags/fashion/"],"until":"2025-01-01","maxItems":200,"skill":true}'
```

---

## Instagram Hashtag Scraper — Scenarios

Actor: `INSTAGRAM_HASHTAG_SCRAPER_ID`

Accepts `startUrls` (hashtag URLs) or a `keyword` string. Toggle `getPosts` / `getReels` to filter content type.

### Scrape a hashtag by URL
```bash
-d '{"startUrls":["https://www.instagram.com/explore/tags/foodie/"],"maxItems":100,"skill":true}'
```

### Scrape by keyword (discovery mode)
```bash
-d '{"keyword":"sustainable fashion","maxItems":100,"skill":true}'
```

### Reels only from a hashtag
```bash
-d '{"startUrls":["https://www.instagram.com/explore/tags/travel/"],"getPosts":false,"getReels":true,"maxItems":100,"skill":true}'
```

### Multiple hashtags in one run
```bash
-d '{"startUrls":["https://www.instagram.com/explore/tags/fitness/","https://www.instagram.com/explore/tags/gym/","https://www.instagram.com/explore/tags/workout/"],"maxItems":200,"skill":true}'
```

---

## Instagram Location Scraper — Scenarios

Actor: `INSTAGRAM_LOCATION_SCRAPER_ID`

Accepts `startUrls` (location URLs) or `locationIds` (numeric IDs from URLs).

### Single location by URL
```bash
-d '{"startUrls":["https://www.instagram.com/explore/locations/213131048/berlin-germany/"],"maxItems":200,"skill":true}'
```

### Multiple locations in one run
```bash
-d '{"startUrls":["https://www.instagram.com/explore/locations/213131048/berlin-germany/","https://www.instagram.com/explore/locations/213385402/paris-france/","https://www.instagram.com/explore/locations/212988663/rome-italy/"],"maxItems":300,"skill":true}'
```

### Location by ID (when you have IDs from a database)
```bash
-d '{"locationIds":["213131048","213385402"],"maxItems":200,"skill":true}'
```

### Location with date filter
```bash
-d '{"startUrls":["https://www.instagram.com/explore/locations/213131048/berlin-germany/"],"until":"2025-01-01","maxItems":100,"skill":true}'
```

---

## Instagram Comments Scraper — Scenarios

Actor: `INSTAGRAM_COMMENTS_SCRAPER_ID`

Accepts `startUrls` (post/reel URLs) or `postIds` (shortcodes from URLs).

### Comments from a single post
```bash
-d '{"startUrls":["https://www.instagram.com/p/DRvit9Ejgel/"],"maxItems":100,"skill":true}'
```

### Comments from multiple posts
```bash
-d '{"startUrls":["https://www.instagram.com/p/DRvit9Ejgel/","https://www.instagram.com/p/C0JD3tntcmy/","https://www.instagram.com/p/ABC123XYZ/"],"maxItems":200,"skill":true}'
```

### Comments by post ID (shortcode)
```bash
-d '{"postIds":["DRvit9Ejgel","C0JD3tntcmy"],"maxItems":100,"skill":true}'
```

### Comments with duplicate handling enabled (large comment sections)
```bash
-d '{"startUrls":["https://www.instagram.com/p/DRvit9Ejgel/"],"continueOnDuplicates":true,"maxItems":500,"skill":true}'
```

---

## Instagram User Scraper — Scenarios

Actor: `INSTAGRAM_USER_SCRAPER_ID`

Accepts `keywords` (discovery search), `usernames`/`handles`, `userIds`, or `startUrls` (profile URLs). Optionally scrape `followers` and `following` lists.

### Discover users by keyword (most cost-effective — 40 free profiles per search)
```bash
-d '{"keywords":["fitness influencer"],"maxItems":100,"skill":true}'
```

### Scrape specific profiles by username
```bash
-d '{"usernames":["nike","adidas","puma"],"skill":true}'
```

### Scrape profiles by URL
```bash
-d '{"startUrls":["https://www.instagram.com/nike/","https://www.instagram.com/gordonramsay/"],"skill":true}'
```

### Scrape profile including follower list
```bash
-d '{"usernames":["nike"],"scrapeFollowers":true,"maxItems":500,"skill":true}'
```

### Scrape profile including following list
```bash
-d '{"usernames":["nike"],"scrapeFollowing":true,"maxItems":200,"skill":true}'
```

---

## Output

**Post object (Scraper / Hashtag / Location actors):**
```json
{
  "id": "3245142029192513970",
  "code": "C0JD3tntcmy",
  "url": "https://www.instagram.com/p/C0JD3tntcmy/",
  "createdAt": "2023-11-27T07:48:34.000Z",
  "likeCount": 114,
  "commentCount": 5,
  "caption": "#dogs #love ...",
  "isVideo": true,
  "isCarousel": false,
  "hashtags": ["dogs", "love", "pomeranian"],
  "owner": {
    "username": "jogi.lapki.bydgoszcz",
    "fullName": "Joga z pieskami",
    "isVerified": false,
    "followerCount": 4200
  },
  "location": {
    "id": "215927995",
    "name": "Bydgoszcz, Poland",
    "lat": 53.1222,
    "lng": 17.9986
  },
  "video": {
    "url": "https://...",
    "duration": 28.281,
    "playCount": 3321
  }
}
```

**Comment object (Comments Scraper):**
```json
{
  "id": "17858893269000001",
  "text": "Amazing shot! 🔥",
  "likeCount": 42,
  "createdAt": "2025-01-15T10:22:00.000Z",
  "owner": {
    "username": "superfan_ig",
    "fullName": "Super Fan",
    "isVerified": false
  }
}
```

**Profile object (User Scraper):**
```json
{
  "username": "nike",
  "fullName": "Nike",
  "biography": "Just Do It.",
  "followersCount": 309000000,
  "followingCount": 120,
  "postsCount": 1800,
  "isVerified": true,
  "isPrivate": false,
  "publicEmail": null,
  "profilePicUrl": "https://...",
  "externalUrl": "https://www.nike.com"
}
```

## Code Integration

These skills can be integrated directly into your code. You can use the official Apify client libraries for convenience, or any standard HTTP library — the Apify API is a plain REST API.

**Python**

```bash
pip install apify-client
```

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("INSTAGRAM_SCRAPER_ID").call(run_input={
    "startUrls": ["https://www.instagram.com/nike/"],
    "maxItems": 100,
    "skill": True
})
items = list(client.dataset(run["defaultDatasetId"]).iterate_items())
```

**JavaScript / TypeScript**

```bash
npm install apify-client
```

```js
import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_APIFY_TOKEN" });
const run = await client.actor("INSTAGRAM_SCRAPER_ID").call({
  startUrls: ["https://www.instagram.com/nike/"],
  maxItems: 100,
  skill: true,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

> Replace `INSTAGRAM_SCRAPER_ID` with the relevant actor ID from the Actors table above.

## Guardrails

- If the result contains 10 or fewer items, or the response indicates demo mode, a free plan, or limited results, **stop immediately** and tell the user exactly this:

  > "This actor requires a paid Apify plan to return real data. Please upgrade at [apify.com/pricing?fpr=yhdrb](https://apify.com/pricing?fpr=yhdrb) and try again."

- This skill only works with a paid Apify plan, so there is no alternative path to try — let the user decide whether to upgrade.