# Instagram Sponsorship & Promo Intelligence (`scalogik/instagram-sponsorship-promo-intelligence`) Actor

Detect sponsored posts, promo codes, affiliate links, CTAs, and creator-brand relationships from Instagram post records.

- **URL**: https://apify.com/scalogik/instagram-sponsorship-promo-intelligence.md
- **Developed by:** [Scalogik LLC](https://apify.com/scalogik) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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 Sponsorship & Promo Intelligence

![Instagram Sponsorship & Promo Intelligence marketplace cover](https://files.manuscdn.com/user_upload_by_module/session_file/310519663080398616/yrtqYcKRnbssMebd.png)

Turn Instagram post records into **deduplicated creator sponsorship, promo-code, affiliate, CTA, and brand-collaboration intelligence**.

This Actor is an analysis layer, not another generic Instagram scraper. Supply post or Reel records inline, connect an existing Apify dataset, call Apify’s Instagram Scraper for convenience, or select another upstream Actor. The Actor normalizes common Instagram schemas and returns one ranked, evidence-backed row per creator.

> **Best for:** DTC brands, affiliate managers, influencer agencies, competitor-research teams, and developers building creator-discovery or campaign-analysis pipelines.

### Why use this Actor?

Raw Instagram scrapers return posts. This Actor turns those posts into a shortlist: who appears to promote brands, which promo codes and offers they use, which brands or collaborators appear in the evidence, what calls to action are present, and why each creator received its score.

The core analysis uses deterministic rules. It requires **no LLM, browser, proxy, Instagram login, or paid third-party API**. If you select an upstream Actor, that Actor’s usage is billed separately to your Apify account.[1]

| Capability | What you receive |
|---|---|
| Sponsorship evidence | Structured paid-partnership flags and explicit disclosure language such as `#ad`, `#sponsored`, paid partnership, affiliate disclosure, and selected multilingual labels |
| Promo-code extraction | Conservative codes found near cues such as “use code,” “promo code,” “Gutscheincode,” or `優惠碼` |
| Offer extraction | Percentage discounts such as `20% off` or `save 15%` |
| Affiliate evidence | Explicit affiliate disclosures and links containing common affiliate/referral parameters |
| Brand relationships | Paid partners, coauthors, tagged accounts, @mentions, and optional brand-keyword matches |
| CTA classification | Link in bio, shop now, buy now, order now, sign up, download, book, DM, and limited-time language |
| Creator aggregation | One deduplicated result per creator with scores, first/latest evidence dates, and up to ten evidence posts |

### Data-source options

| Source mode | Input | Cost and purpose |
|---|---|---|
| `inline` | `records` | Free core analysis for testing and integrations |
| `dataset` | `datasetId` | Analyze records already stored in Apify |
| `instagram_scraper` | `instagramUrls` or `searchQueries` | Convenience mode using `apify/instagram-scraper`; upstream usage is separate |
| `upstream_actor` | `upstreamActorId` and `upstreamActorInput` | Connect another compatible Actor you trust |

Apify datasets support JSON, JSONL, CSV, Excel, XML, HTML, and RSS exports.[2] The Actor’s output schema also makes results discoverable to API and MCP clients.[3]

### Quick start: inline records

```json
{
  "sourceMode": "inline",
  "records": [
    {
      "id": "campaign-001",
      "ownerUsername": "samplecreator",
      "ownerFullName": "Sample Creator",
      "caption": "Paid partnership with @northstar. Save 20% when you use code STAR20. Shop now: https://shop.example/products?aff=samplecreator",
      "url": "https://www.instagram.com/p/DEMO123/",
      "timestamp": "2026-08-20T10:00:00Z",
      "likesCount": 4200,
      "commentsCount": 180,
      "isPaidPartnership": true,
      "paidPartnershipPartners": ["northstar"]
    }
  ],
  "minimumConfidence": 35,
  "requireSponsorshipSignal": true,
  "includeEvidencePosts": true
}
```

### Analyze an existing Apify dataset

```json
{
  "sourceMode": "dataset",
  "datasetId": "my-instagram-posts",
  "minimumConfidence": 35,
  "requirePromoCode": false,
  "maxSourceRecords": 5000,
  "maxLeads": 500
}
```

### Collect and analyze public Instagram posts

```json
{
  "sourceMode": "instagram_scraper",
  "instagramUrls": [
    "https://www.instagram.com/nike/",
    "https://www.instagram.com/adidas/"
  ],
  "maxPostsPerSource": 30,
  "minimumConfidence": 35
}
```

This mode calls `apify/instagram-scraper`. The upstream run is visible in the `OUTPUT` summary, and its charges are separate from this Actor’s creator-intelligence results.

### Input reference

| Field | Default | Description |
|---|---:|---|
| `sourceMode` | `inline` | `inline`, `dataset`, `instagram_scraper`, or `upstream_actor` |
| `records` | Demo record | Inline post or Reel objects; maximum 5,000 in the input UI |
| `datasetId` | Empty | Existing Apify dataset ID or name; URLs and tokens are rejected |
| `instagramUrls` | Empty | Public post, Reel, profile, hashtag, or place URLs |
| `searchQueries` | Empty | Instagram hashtag-discovery terms for convenience mode |
| `maxPostsPerSource` | `30` | Per-source upstream safety cap; maximum 200 |
| `upstreamActorId` | Empty | Actor ID or `username/actor-name` |
| `upstreamActorInput` | Empty | Secret JSON input passed to the selected Actor |
| `brandKeywords` | Empty | Brand names or handles to match in captions |
| `nicheKeywords` | Empty | Require at least one caption match before analysis |
| `minimumConfidence` | `35` | Minimum 0–100 creator lead score |
| `requirePromoCode` | `false` | Return only creators with a detected code |
| `requireSponsorshipSignal` | `true` | Exclude generic mention/CTA-only content |
| `maxSourceRecords` | `5000` | Hard processing cap; maximum 50,000 |
| `maxLeads` | `500` | Hard result cap; maximum 10,000 |
| `includeEvidencePosts` | `true` | Include up to ten compact evidence posts per creator |

### Supported input aliases

The normalizer supports common fields used by Instagram Actors and datasets. Examples include `caption`, `text`, `description`, `ownerUsername`, `username`, `user_posted`, `postId`, `post_id`, `shortCode`, `url`, `date_posted`, `likesCount`, `num_comments`, `video_view_count`, `mentions`, `tagged_users`, `coauthor_producers`, `is_paid_partnership`, and `has_handshake`.

Records without a creator identity or caption are skipped and counted in `OUTPUT`. Duplicate posts are matched by ID, shortcode, URL, or a deterministic fingerprint.

### Output

The default dataset contains one row per creator:

```json
{
  "recordType": "creator_sponsorship_intelligence",
  "creatorUsername": "samplecreator",
  "creatorName": "Sample Creator",
  "creatorProfileUrl": "https://www.instagram.com/samplecreator/",
  "leadScore": 83,
  "confidenceTier": "high",
  "commercialPosts": 1,
  "totalPostsAnalyzed": 1,
  "sponsorshipSignals": ["paid_partnership", "structured_paid_partnership"],
  "promoCodes": ["STAR20"],
  "discountOffers": ["20% off"],
  "affiliateLinks": ["https://shop.example/products?aff=samplecreator"],
  "brandPartners": ["northstar"],
  "brandMentions": ["northstar"],
  "collaborationPartners": ["northstar"],
  "ctaTypes": ["shop_now"],
  "firstSeenAt": "2026-08-20T10:00:00.000Z",
  "lastSeenAt": "2026-08-20T10:00:00.000Z",
  "topEvidenceUrl": "https://www.instagram.com/p/DEMO123/",
  "methodVersion": "0.1.0"
}
```

The non-billable `OUTPUT` record contains the completion status, source metadata, filters, counts, skipped-record reasons, and truncation indicators. Credential-like fields are removed recursively before source diagnostics are stored.

### API usage

Replace `<USERNAME>` and `<APIFY_TOKEN>` with your Actor owner and Apify API token.

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('<USERNAME>/instagram-sponsorship-promo-intelligence').call({
  sourceMode: 'dataset',
  datasetId: 'my-instagram-posts',
  minimumConfidence: 35,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("<USERNAME>/instagram-sponsorship-promo-intelligence").call(
    run_input={
        "sourceMode": "dataset",
        "datasetId": "my-instagram-posts",
        "minimumConfidence": 35,
    }
)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/<USERNAME>~instagram-sponsorship-promo-intelligence/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceMode":"dataset","datasetId":"my-instagram-posts"}'
```

The Apify API can start Actors, retrieve datasets, inspect runs, and manage tasks programmatically.[4]

### Scoring method

Each post receives a deterministic 0–100 confidence score. Structured paid-partnership metadata and explicit disclosures carry the greatest weight. Promo codes, affiliate signals, collaboration partners, brand mentions, discounts, and CTAs add smaller weights. Evidence diversity adds confidence, while generic CTA-only posts remain below the default threshold.

Creator scores combine the strongest post, repeated commercial evidence, unique partner relationships, promo-code evidence, and disclosure quality. The method is versioned in every row so downstream systems can reproduce or audit changes.

### Pricing

Recommended launch pricing uses Apify pay per event:

| Event | Price |
|---|---:|
| `apify-actor-start` | `$0.00005` per run |
| `apify-default-dataset-item` | `$0.003` per creator-intelligence result |

Apify recommends the synthetic Actor-start event and notes that it covers the first five seconds of compute when enabled.[5] One default-dataset item maps directly to one visible, deduplicated creator result. Inline and dataset analysis have no paid external dependency; upstream Actor usage is separate.

### Accuracy and limitations

A reproducible evaluation on 1,000 public sample records passed all structured paid-partnership labels when full metadata was present. Caption-only detection was deliberately conservative and did not recover partnership labels whose captions lacked supported disclosure language. Review [the quality report](./QA_REPORT.md) before publishing claims.

This Actor does **not**:

- infer every undisclosed sponsorship;
- determine whether a contract exists;
- classify image-only disclosures;
- access private Instagram content;
- contact creators or automate outreach;
- guarantee legal, advertising-standard, or platform-policy compliance.

A promo code or sales CTA can represent self-promotion rather than a third-party sponsorship. For that reason, every result includes its evidence instead of presenting the score as fact.

### Responsible use

Process only public or otherwise authorized data. Apply appropriate retention, security, privacy, and outreach controls. Public social data may still contain personal data; assess your lawful basis and applicable obligations before storing or using it. This independent Actor is not affiliated with, endorsed by, or sponsored by Instagram or Meta.

### Support

When reporting an issue, include the run ID, source mode, a sanitized example record, expected result, and observed result. Never post API tokens, cookies, session values, or private datasets in a public issue.

### References

[1]: https://docs.apify.com/api/v2 "Apify API documentation"

[2]: https://docs.apify.com/storage/dataset "Dataset — Apify Documentation"

[3]: https://docs.apify.com/actors/development/actor-definition/output-schema "Actor output schema — Apify Documentation"

[4]: https://docs.apify.com/academy/api/run-actor-and-retrieve-data-via-api "Run Actor and retrieve data via API — Apify Academy"

[5]: https://docs.apify.com/actors/publishing/monetize/pay-per-event "Actor pay-per-event pricing model — Apify Documentation"

# Actor input Schema

## `sourceMode` (type: `string`):

Inline records require no paid dependency. Dataset and upstream modes analyze data already available in your Apify account. Instagram Scraper mode calls apify/instagram-scraper and is billed separately.

## `records` (type: `array`):

Post or Reel records from any source. Common Instagram Actor field names are normalized automatically.

## `datasetId` (type: `string`):

Existing Apify dataset containing Instagram post records. URLs and API tokens are not accepted.

## `instagramUrls` (type: `array`):

Public Instagram post, Reel, profile, hashtag, or place URLs. Used only in Instagram Scraper mode.

## `searchQueries` (type: `array`):

Hashtag discovery terms for Instagram Scraper mode, without #. URLs take priority when both are supplied.

## `maxPostsPerSource` (type: `integer`):

Safety limit passed to the official Instagram Scraper in convenience mode.

## `searchLimit` (type: `integer`):

Maximum discovery results requested from the official Instagram Scraper.

## `upstreamActorId` (type: `string`):

Actor ID or username/actor-name. Used only in advanced upstream Actor mode.

## `upstreamActorInput` (type: `object`):

JSON input passed to the selected upstream Actor. The Actor strips credential-like fields from diagnostics, but secrets should only be supplied in schema fields that the upstream Actor marks as secret.

## `brandKeywords` (type: `array`):

Optional brand names or handles to detect even when they are not tagged explicitly.

## `nicheKeywords` (type: `array`):

When supplied, only posts whose captions contain at least one niche keyword are analyzed.

## `minimumConfidence` (type: `integer`):

Return only creator intelligence rows scoring at or above this deterministic 0–100 threshold.

## `requirePromoCode` (type: `boolean`):

Return only creators with at least one conservatively detected discount or promo code.

## `requireSponsorshipSignal` (type: `boolean`):

Exclude generic mentions and CTA-only posts that lack stronger sponsorship, promo, affiliate, or offer evidence.

## `maxSourceRecords` (type: `integer`):

Hard processing cap that bounds runtime and memory.

## `maxLeads` (type: `integer`):

Hard output cap. Highest-scoring creators are returned first.

## `includeEvidencePosts` (type: `boolean`):

Include up to 10 sanitized supporting posts per creator result.

## `debug` (type: `boolean`):

Write additional non-secret diagnostics to the OUTPUT record.

## Actor input object example

```json
{
  "sourceMode": "inline",
  "records": [
    {
      "id": "demo-1",
      "ownerUsername": "samplecreator",
      "ownerFullName": "Sample Creator",
      "caption": "Paid partnership with @northstar. Save 20% when you use code STAR20. Shop now: https://shop.example/products?aff=samplecreator",
      "url": "https://www.instagram.com/p/DEMO123/",
      "timestamp": "2026-08-20T10:00:00Z",
      "likesCount": 4200,
      "commentsCount": 180,
      "isPaidPartnership": true,
      "paidPartnershipPartners": [
        "northstar"
      ]
    }
  ],
  "datasetId": "my-instagram-posts",
  "maxPostsPerSource": 30,
  "searchLimit": 20,
  "upstreamActorId": "apify/instagram-scraper",
  "minimumConfidence": 35,
  "requirePromoCode": false,
  "requireSponsorshipSignal": true,
  "maxSourceRecords": 5000,
  "maxLeads": 500,
  "includeEvidencePosts": true,
  "debug": false
}
```

# Actor output Schema

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

One deduplicated, evidence-backed sponsorship and promotion intelligence row per creator.

## `summary` (type: `string`):

Source metadata, filters, skipped-record counts, limits, and completion status.

# 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 = {
    "sourceMode": "inline",
    "records": [
        {
            "id": "demo-1",
            "ownerUsername": "samplecreator",
            "ownerFullName": "Sample Creator",
            "caption": "Paid partnership with @northstar. Save 20% when you use code STAR20. Shop now: https://shop.example/products?aff=samplecreator",
            "url": "https://www.instagram.com/p/DEMO123/",
            "timestamp": "2026-08-20T10:00:00Z",
            "likesCount": 4200,
            "commentsCount": 180,
            "isPaidPartnership": true,
            "paidPartnershipPartners": [
                "northstar"
            ]
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("scalogik/instagram-sponsorship-promo-intelligence").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 = {
    "sourceMode": "inline",
    "records": [{
            "id": "demo-1",
            "ownerUsername": "samplecreator",
            "ownerFullName": "Sample Creator",
            "caption": "Paid partnership with @northstar. Save 20% when you use code STAR20. Shop now: https://shop.example/products?aff=samplecreator",
            "url": "https://www.instagram.com/p/DEMO123/",
            "timestamp": "2026-08-20T10:00:00Z",
            "likesCount": 4200,
            "commentsCount": 180,
            "isPaidPartnership": True,
            "paidPartnershipPartners": ["northstar"],
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("scalogik/instagram-sponsorship-promo-intelligence").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 '{
  "sourceMode": "inline",
  "records": [
    {
      "id": "demo-1",
      "ownerUsername": "samplecreator",
      "ownerFullName": "Sample Creator",
      "caption": "Paid partnership with @northstar. Save 20% when you use code STAR20. Shop now: https://shop.example/products?aff=samplecreator",
      "url": "https://www.instagram.com/p/DEMO123/",
      "timestamp": "2026-08-20T10:00:00Z",
      "likesCount": 4200,
      "commentsCount": 180,
      "isPaidPartnership": true,
      "paidPartnershipPartners": [
        "northstar"
      ]
    }
  ]
}' |
apify call scalogik/instagram-sponsorship-promo-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scalogik/instagram-sponsorship-promo-intelligence"
        }
    }
}

```

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/qasrCwM4f2n8v82Hq/builds/p78ep5uN5k0WwOh4H/openapi.json