# Instagram Brand Mentions & UGC Monitor (`data-slayer/instagram-brand-monitor`) Actor

Collect newly observed public Instagram tagged posts, keyword results, and campaign hashtag posts in one deduplicated feed with persistent first-seen state.

- **URL**: https://apify.com/data-slayer/instagram-brand-monitor.md
- **Developed by:** [Data Slayer](https://apify.com/data-slayer) (community)
- **Categories:** Social media, Marketing, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $40.00 / 1,000 completed monitor scans

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Instagram Brand Mentions & UGC Monitor

Turn public tagged posts, campaign hashtags, and brand keyword results into one deduplicated feed of newly observed Instagram content, with match evidence and first-seen timestamps ready for review or automation.

### What this Actor delivers

Each bounded scan can check one public brand account's tagged posts and Reels, up to five keyword phrases, and up to five recent campaign hashtag feeds. The Actor joins observations by stable Instagram media ID, preserves every configured source that found an item, and remembers what it has seen for the selected monitor.

Scheduled runs return only newly observed content when you reuse the same `monitorId`. A different monitor ID starts a separate state history.

### Input example

```json
{
  "monitorId": "patagonia-fall-2026",
  "brandAccount": "patagonia",
  "keywords": ["patagonia", "worn wear"],
  "hashtags": ["patagonia", "wornwear"],
  "firstRunBehavior": "emit_current",
  "keywordMatchPolicy": "include_configured_matches",
  "maxPagesPerInput": 1,
  "maxItemsPerInput": 50,
  "maxItemsPerRun": 250
}
```

Add at least one account, keyword, or hashtag. The maximum is one account, five keywords, and five hashtags.

### First and recurring runs

- `emit_current` returns currently observed posts and saves the baseline.
- `baseline_only` saves the current baseline without emitting content rows.

State keys combine the authenticated run user and monitor ID. Media IDs unseen for more than 180 days expire from the monitor state.

Concurrent runs for the same user and `monitorId` do not scan in parallel: one run holds a Request Queue lock and another returns a busy outcome. A platform lock expires after a crashed run so later recovery remains possible.

### Match confidence

Every delivered row keeps configured-match evidence. It also reports whether the configured term was literally confirmed in the caption, structured hashtag, or structured @mention.

Instagram keyword search can surface related content without the exact phrase. Keep those labeled results with `include_configured_matches`, or select `literal_matches_only` for a narrower feed. Tagged-account and hashtag evidence is preserved even when the caption does not repeat the term.

### Output

The default Dataset contains one `content` row for each newly delivered, deduplicated media ID. Rows include:

- stable media, row, deduplication, monitor, and scan IDs;
- the public Instagram post or Reel URL and public author metadata;
- caption, posting and observation times, and first-seen time;
- engagement values when available;
- public media URLs and dimensions when available;
- normalized hashtags and mentions;
- ordered configured-source matches and literal-confirmation locations.

Unavailable fields are `null`; missing metrics are not converted to zero.

Every run also writes `RUN_SUMMARY` to the default key-value store. It reports completed, unavailable, and unscanned inputs; pages and retries; observed, filtered, known, and new item counts; state status; limits; warnings; and billed events. The Dataset contains content rows only.

Dataset delivery is at least once across process crashes. If a process stops after appending rows but before the final checkpoint, retrying the same run can append those rows again. Consumers should deduplicate with `dedupeKey` or `mediaId`. Billing recovery compares authoritative charged-event counts for the current run before retrying an event; live-cloud recovery remains part of the private smoke gate.

### Limits and failure handling

- One brand account.
- Up to five keyword phrases.
- Up to five hashtags.
- One to three pages per monitored input.
- Up to 100 observed items per input.
- Up to 500 observed items per run.

A successful scan with no new content is distinct from a retrieval failure. If every source is unavailable before usable state can be committed, the run fails and no completed-monitor-scan event is charged.

Free users are limited to three monitored pages per run, one page per input, and 30 completed scans per calendar month. Paid tiers receive the full published limits.

### Pricing

Customers pay for bounded monitoring coverage, not for new-item count.

| Plan | Completed monitor scan | Additional monitored page |
|---|---:|---:|
| Free | $0.060 | $0.007, unreachable under the current Free page cap |
| Bronze | $0.050 | $0.006 |
| Silver | $0.045 | $0.0055 |
| Gold | $0.040 | $0.005 |
| Platinum | $0.040 | $0.005 |
| Diamond | $0.040 | $0.005 |

One completed-monitor-scan event includes the first three completed monitored pages. Each completed page after the first three uses an `additional-monitored-page` event. Retries and returned items are not billed separately. The automatic `$0.00005` Actor-start event applies to every plan.

These are the coordinator-selected launch-candidate prices and are not live until the Actor is created and published.

### Scheduling

Create an Apify Task with a stable `monitorId`, then add an Apify Schedule. Use webhooks or integrations to send the new-item Dataset and `RUN_SUMMARY` to your destination. The Actor does not create or manage schedules itself.

### Coverage and responsible use

This Actor observes bounded public Instagram results. It is not an exhaustive social-listening index and does not promise every mention, complete historical backfill, deterministic keyword relevance, comments, Stories, deleted content, or private-account access. Media URLs can expire.

Instagram content can contain personal data and copyrighted material. Use results only for a lawful purpose, follow applicable rules, and do not use this Actor to access private content or make automated legal, employment, credit, or eligibility decisions about individuals.

# Actor input Schema

## `monitorId` (type: `string`):

Stable lowercase ID. Reuse it on scheduled runs to keep first-seen state.

## `brandAccount` (type: `string`):

One public Instagram username or profile URL.

## `keywords` (type: `array`):

Up to 5 exact phrases. Results retain configured and literal-match evidence.

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

Up to 5 hashtags, with or without #.

## `firstRunBehavior` (type: `string`):

Return current posts or save them only as a baseline.

## `keywordMatchPolicy` (type: `string`):

Keep all configured search results or only literal caption, hashtag, or @mention matches.

## `maxPagesPerInput` (type: `integer`):

Check 1–3 pages for each configured source.

## `maxItemsPerInput` (type: `integer`):

Stop keeping items for an account, keyword, or hashtag after this many unique media IDs. Available results can be lower.

## `maxItemsPerRun` (type: `integer`):

Hard cap across all monitored inputs. When reached, the Actor stops checking more pages or inputs and reports which inputs were not scanned.

## Actor input object example

```json
{
  "monitorId": "patagonia-campaign",
  "brandAccount": "patagonia",
  "keywords": [
    "patagonia"
  ],
  "hashtags": [
    "patagonia"
  ],
  "firstRunBehavior": "emit_current",
  "keywordMatchPolicy": "include_configured_matches",
  "maxPagesPerInput": 1,
  "maxItemsPerInput": 50,
  "maxItemsPerRun": 250
}
```

# Actor output Schema

## `results` (type: `string`):

One row per newly observed media ID.

## `dataset_table` (type: `string`):

Default table view for export.

## `run_summary` (type: `string`):

Coverage, state, limits, errors, and billed monitor events.

# 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 = {
    "monitorId": "patagonia-campaign",
    "brandAccount": "patagonia",
    "keywords": [
        "patagonia"
    ],
    "hashtags": [
        "patagonia"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("data-slayer/instagram-brand-monitor").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 = {
    "monitorId": "patagonia-campaign",
    "brandAccount": "patagonia",
    "keywords": ["patagonia"],
    "hashtags": ["patagonia"],
}

# Run the Actor and wait for it to finish
run = client.actor("data-slayer/instagram-brand-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "monitorId": "patagonia-campaign",
  "brandAccount": "patagonia",
  "keywords": [
    "patagonia"
  ],
  "hashtags": [
    "patagonia"
  ]
}' |
apify call data-slayer/instagram-brand-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,data-slayer/instagram-brand-monitor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/zQ3dd68Mi8kRAPXL2/builds/zh2xUz58lS8XC4788/openapi.json