# Instagram Hashtag Analytics Scraper (`automation-lab/instagram-hashtag-analytics`) Actor

Sample public Instagram hashtag posts and reels and return per-hashtag engagement aggregates, top posts, top authors, observed records, and snapshot time.

- **URL**: https://apify.com/automation-lab/instagram-hashtag-analytics.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Hashtag Analytics Scraper

Create repeatable **Instagram hashtag analytics** snapshots from public hashtag pages.
The Actor samples visible posts and reels, enriches public engagement metadata, and returns one typed result per hashtag with totals, averages, media mix, top posts, top authors, observed records, and snapshot time.

Use it to compare campaign hashtags, watch how a public content sample changes between scheduled runs, or feed hashtag-level metrics into a spreadsheet or dashboard.
No Instagram login is required.

> The results describe the records observed during the run. They are not Instagram's complete historical count or a guarantee that every post using a hashtag was visible.

### What does Instagram Hashtag Analytics Scraper do?

For every requested hashtag, the Actor:

1. opens the public Instagram hashtag surface;
2. collects a bounded sample of unique post and reel URLs;
3. optionally opens each public record to read available creator, caption, timestamp, like, and comment metadata;
4. calculates observed totals and averages;
5. ranks the top sampled posts and authors; and
6. saves one timestamped analytics record to the default dataset.

The underlying `observedRecords` array stays in the same result, so analysts can audit which public records contributed to every aggregate.

### Who is this Instagram analytics Actor for?

- **Social media managers** comparing branded and campaign hashtags.
- **Marketing analysts** collecting recurring observed-sample snapshots.
- **Creator teams** finding authors visible in a hashtag sample.
- **Agencies** exporting campaign evidence for clients.
- **Data engineers** loading structured hashtag snapshots into BI tools.
- **Researchers** studying publicly visible Instagram content without a login workflow.

Choose a post-level scraper instead when you need one dataset row per post rather than one aggregate row per hashtag.

### Why use observed hashtag snapshots?

Instagram's public surface changes over time and does not expose a complete public historical API.
This Actor makes that limitation explicit instead of presenting sampled metrics as platform-wide totals.

Each row includes:

- `snapshotAt` for recurring comparisons;
- `sampleSize` so metrics retain their denominator;
- `postsCount` and `reelsCount` for visible media mix;
- nullable metric totals and averages when Instagram exposes them;
- `topPosts` ranked by known likes plus comments;
- `topAuthors` ranked within the observed sample; and
- `observedRecords` for reproducibility.

### What Instagram hashtag data can I extract?

| Field | Meaning |
| --- | --- |
| `hashtag` | Normalized hashtag without `#` |
| `sourceUrl` | Public hashtag URL sampled |
| `snapshotAt` | ISO timestamp when analytics were calculated |
| `sampleSize` | Number of unique public records observed |
| `postsCount` / `reelsCount` | Media types in the sample |
| `totalLikes` / `averageLikes` | Sum and average over records with public like counts |
| `totalComments` / `averageComments` | Sum and average over records with public comment counts |
| `totalViews` / `averageViews` | Sum and average when public view counts are exposed |
| `totalEngagementActions` | Known likes plus comments in the sample |
| `averageEngagementActions` | Known engagement actions divided by sample size |
| `observedEarliestAt` / `observedLatestAt` | Public timestamp range found in the sample |
| `topPosts` | Highest observed known engagement records |
| `topAuthors` | Creator ranking within the sample |
| `observedRecords` | Public records used to calculate the snapshot |

Nullable values mean Instagram did not expose that field publicly for the sampled record.
They do not mean zero.

### How to run the Actor

1. Open **Instagram Hashtag Analytics Scraper** in Apify Console.
2. Enter one or more hashtags, such as `apify` or `webscraping`.
3. Keep `sampleSize` small for a quick first run.
4. Leave detail enrichment enabled for engagement and creator fields.
5. Click **Start**.
6. Open the default dataset to review or export the hashtag snapshots.
7. For monitoring, create an Apify Schedule and retain each run's `snapshotAt` results in your destination.

A small real input:

```json
{
  "hashtags": ["apify"],
  "sampleSize": 3,
  "includePosts": true,
  "includeReels": true,
  "includeDetails": true,
  "topPostsLimit": 3,
  "topAuthorsLimit": 3,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

### Input parameters

| Input | Type | Default | Notes |
| --- | --- | --- | --- |
| `hashtags` | string array | `['apify']` | Up to 20 tags, with or without `#` |
| `startUrls` | request list | empty | Instagram `/explore/tags/` or `/popular/` URLs |
| `sampleSize` | integer | `12` | 1–50 observed records per hashtag |
| `includePosts` | boolean | `true` | Include photo and carousel post cards |
| `includeReels` | boolean | `true` | Include reel cards |
| `includeDetails` | boolean | `true` | Open public record pages for engagement metadata |
| `topPostsLimit` | integer | `5` | 0–20 ranked observed posts |
| `topAuthorsLimit` | integer | `5` | 0–20 ranked observed creators |
| `proxyConfiguration` | object | direct | Optional standard Apify Proxy; premium groups/country routing are rejected |

Hashtag text inputs and URL inputs are combined and deduplicated.
At least one source is required.
At least one of posts or reels must remain enabled.

### Example output

A real local run for `#apify` returned one row shaped like this:

```json
{
  "hashtag": "apify",
  "sourceUrl": "https://www.instagram.com/explore/tags/apify/",
  "snapshotAt": "2026-08-04T03:30:15.172Z",
  "sampleSize": 2,
  "postsCount": 0,
  "reelsCount": 2,
  "totalLikes": 19472,
  "totalComments": 28150,
  "averageLikes": 9736,
  "averageComments": 14075,
  "totalEngagementActions": 47622,
  "averageEngagementActions": 23811,
  "observedLatestAt": "2026-05-04T03:14:57.000Z",
  "topPosts": [
    {
      "postUrl": "https://www.instagram.com/reel/DX5rTD_soy2/",
      "shortcode": "DX5rTD_soy2",
      "mediaType": "reel",
      "likesCount": 13000,
      "commentsCount": 25000,
      "authorUsername": "msbintel"
    }
  ],
  "topAuthors": [
    {
      "username": "msbintel",
      "observedPosts": 1,
      "totalEngagementActions": 38000
    }
  ],
  "observedRecords": ["...the records used for this snapshot..."]
}
```

Public values can change between runs.
The exact record URLs are retained in actual dataset output.

### How much does it cost to analyze Instagram hashtags?

Pay-per-event pricing has two parts:

- a **$0.0035 Actor start** charge once per run; and
- a **$0.009064 BRONZE hashtag snapshot** charge for each dataset result.

Top posts, top authors, and observed records are included in the snapshot event and have no separate event charge.
Proxy transfer and platform compute may be billed by Apify according to your plan.

Examples at BRONZE pricing:

| Run | Event cost |
| --- | ---: |
| 1 hashtag | $0.0126 |
| 5 hashtags | $0.0488 |
| 10 hashtags | $0.0941 |
| 20 hashtags | $0.1848 |

Tier discounts can reduce the per-snapshot price for higher Apify plan tiers.
Always review the live pricing panel before a large run.

### Compare campaign hashtags

Submit several tags in one run to create side-by-side snapshots with the same settings:

```json
{
  "hashtags": ["webscraping", "apify"],
  "sampleSize": 10,
  "includePosts": true,
  "includeReels": true,
  "includeDetails": true
}
```

Compare `sampleSize`, media mix, known engagement averages, and top creators.
Do not compare a 5-record snapshot to a 50-record snapshot without retaining the sample-size context.

### Monitor hashtag trends with schedules

For a recurring workflow:

1. save a production input as an Apify Task;
2. attach a daily or weekly Schedule;
3. send each completed run to Google Sheets, a webhook, or your data warehouse;
4. use `hashtag` plus `snapshotAt` as the snapshot key; and
5. compare changes in observed metrics and records.

The Actor produces snapshots but does not send alerts by itself.
Use Apify integrations or your downstream automation for notifications.

### Export and integration patterns

Default dataset results can be exported as JSON, CSV, Excel, XML, or RSS through Apify.
Common workflows include:

- campaign comparison in Google Sheets;
- a dashboard grouped by `hashtag` and `snapshotAt`;
- creator outreach research from `topAuthors`;
- sampled-content review from `topPosts`;
- post-level auditing by flattening `observedRecords`; and
- scheduled ETL through webhooks or the Apify API.

Keep the raw snapshot row when flattening nested arrays so the aggregate remains auditable.

### Run through the Apify API

Replace `YOUR_TOKEN` with an Apify API token.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~instagram-hashtag-analytics/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hashtags":["apify"],"sampleSize":5,"includeDetails":true}'
```

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/instagram-hashtag-analytics').call({
  hashtags: ['apify', 'webscraping'],
  sampleSize: 5,
  includeDetails: true,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_TOKEN')
run = client.actor('automation-lab/instagram-hashtag-analytics').call(run_input={
    'hashtags': ['apify'],
    'sampleSize': 5,
    'includeDetails': True,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use with MCP and AI agents

Add the Apify MCP server in Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/instagram-hashtag-analytics"
```

#### Claude Desktop

Add this server object to Claude Desktop's MCP configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/instagram-hashtag-analytics"
    }
  }
}
```

#### Cursor

Open **Settings → Tools & MCP → Add custom MCP** and use the same server URL:
`https://mcp.apify.com?tools=automation-lab/instagram-hashtag-analytics`.

#### VS Code

Add the HTTP server URL to your workspace MCP configuration, then enable the `automation-lab/instagram-hashtag-analytics` Actor tool.

Example prompts showing MCP usage:

- “Using the Apify MCP tool, analyze the public Instagram #apify sample and summarize the top observed creators.”
- “Call Instagram Hashtag Analytics through MCP to compare #webscraping and #apify with the same sample size.”
- “Use MCP to run my campaign hashtag Task and format the returned snapshots for a spreadsheet.”

### Accuracy, limits, and failure behavior

- Results cover the public sample visible to the run, not all Instagram posts.
- Public page ordering can favor popular content and is not guaranteed chronological.
- Login-only, private, removed, age-gated, or region-limited content is unavailable.
- Instagram may omit likes, comments, views, captions, creators, or timestamps.
- `null` means unavailable; zero is an observed numeric value.
- Detail enrichment is slower than URL-only sampling.
- Instagram can rate-limit or challenge a network route.
- The Actor fails rather than returning a misleading empty success when no useful records are found.
- A large `sampleSize` can still yield fewer records when the public page exposes fewer unique cards.

### Proxy guidance and troubleshooting

Direct access is the default and cheapest route.
The optional proxy path supports standard Apify Proxy without a premium group or country setting.
Premium groups and country-specific/residential routing are rejected because they are outside the measured pricing contract; the Actor never silently enables them.

If a run reports no public records:

1. verify the hashtag is public and spelled correctly;
2. try the `apify` prefill to distinguish input scarcity from route failure;
3. inspect the run log for navigation or challenge errors;
4. enable an Apify Proxy configuration only when needed; and
5. reduce `sampleSize` for a bounded diagnostic run.

If totals are `null`, confirm that `includeDetails` is enabled.
Instagram may still hide a metric on individual public records.

### Responsible use and legality

This Actor accesses publicly visible Instagram pages without logging in.
You are responsible for ensuring that your use complies with Instagram's terms, applicable laws, and your organization's policies.

Do not use the Actor to harass people, build sensitive-person profiles, infer protected attributes, or republish personal data without a lawful basis.
Minimize retention, secure exported datasets, honor valid deletion requests, and collect only fields needed for your legitimate purpose.
This documentation is not legal advice.

### Related Automation Lab Actors

- [Instagram Hashtag Posts Scraper](https://apify.com/automation-lab/instagram-hashtag-posts-scraper) — one row per sampled hashtag post or reel.
- [Instagram Hashtag Scraper](https://apify.com/automation-lab/instagram-hashtag-scraper) — hashtag-focused public content extraction.
- [Instagram Profile Posts Scraper](https://apify.com/automation-lab/instagram-profile-posts-scraper) — public post records grouped by profile.
- [Instagram Mentions & Tagged Posts Scraper](https://apify.com/automation-lab/instagram-mentions-tagged-posts-scraper) — public mention and tagged-content workflows.

Use this Actor when the primary result should be a hashtag-level analytics snapshot rather than a post-level row.

### FAQ

#### Does it require an Instagram login?

No. It reads public hashtag and record surfaces.
It cannot access private or login-only content.

#### Is `sampleSize` Instagram's total hashtag post count?

No. It is the number of unique public records observed and used in the snapshot.
The Actor does not claim a platform-wide total.

#### Can I compare snapshots over time?

Yes. Schedule the same Task and store rows by `hashtag` and `snapshotAt`.
Keep settings consistent when comparing observed metrics.

#### Why are view counts null?

Instagram does not consistently expose public views in the same metadata used for likes and comments.
A nullable value prevents false zeros.

#### Can I analyze only reels?

Yes. Set `includePosts` to `false` and keep `includeReels` enabled.
The result still includes the sample media counts and observed records.

#### Why did my run fail with no records?

The hashtag may be empty, private, misspelled, or unavailable from the current network route.
Try a known public hashtag, inspect logs, then configure a proxy if appropriate.

#### Are top authors global Instagram rankings?

No. They are ranked only within the records observed in that hashtag snapshot.

# Actor input Schema

## `hashtags` (type: `array`):

Hashtags to analyze, with or without #. Up to 20 unique hashtags per run.

## `startUrls` (type: `array`):

Optional public URLs such as https://www.instagram.com/explore/tags/apify/. URL hashtags are combined with the Hashtags field.

## `sampleSize` (type: `integer`):

Maximum number of currently visible unique public posts and reels used to calculate each hashtag snapshot.

## `includePosts` (type: `boolean`):

Include public photo and carousel post cards in the observed sample.

## `includeReels` (type: `boolean`):

Include public reel cards in the observed sample.

## `includeDetails` (type: `boolean`):

Open sampled public records to collect available timestamps, captions, creators, likes, and comments. Disable for a faster media-mix snapshot.

## `topPostsLimit` (type: `integer`):

Maximum observed records included in the topPosts engagement ranking.

## `topAuthorsLimit` (type: `integer`):

Maximum creators included in the topAuthors ranking for each observed sample.

## `proxyConfiguration` (type: `object`):

Optional standard Apify Proxy configuration. Direct access is the default. Premium groups and country-specific/residential routing are rejected because they are not part of this Actor's measured pricing contract.

## Actor input object example

```json
{
  "hashtags": [
    "apify"
  ],
  "startUrls": [],
  "sampleSize": 12,
  "includePosts": true,
  "includeReels": true,
  "includeDetails": true,
  "topPostsLimit": 5,
  "topAuthorsLimit": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Engagement aggregates, media mix, top posts, top authors, observed records, and snapshot time.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "hashtags": [
        "apify"
    ],
    "startUrls": [],
    "sampleSize": 12,
    "includePosts": true,
    "includeReels": true,
    "includeDetails": true,
    "topPostsLimit": 5,
    "topAuthorsLimit": 5,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/instagram-hashtag-analytics").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "hashtags": ["apify"],
    "startUrls": [],
    "sampleSize": 12,
    "includePosts": True,
    "includeReels": True,
    "includeDetails": True,
    "topPostsLimit": 5,
    "topAuthorsLimit": 5,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/instagram-hashtag-analytics").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 '{
  "hashtags": [
    "apify"
  ],
  "startUrls": [],
  "sampleSize": 12,
  "includePosts": true,
  "includeReels": true,
  "includeDetails": true,
  "topPostsLimit": 5,
  "topAuthorsLimit": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call automation-lab/instagram-hashtag-analytics --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/instagram-hashtag-analytics",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/NZVCeIwIgz0gP6JxY/builds/7ztiWn7qtHJ0neHuQ/openapi.json