# Instagram User Search (`opspilot.cc/instagram-user-search`) Actor

🔎 Instagram User Search | Who ranks for a keyword, and how big they are Search Instagram for accounts and get every hit with Instagram's own ranking position (0 = the top result) — so you can see who owns a keyword, not just who exists.

- **URL**: https://apify.com/opspilot.cc/instagram-user-search.md
- **Developed by:** [wang wei](https://apify.com/opspilot.cc) (community)
- **Stats:** 109 total users, 6 monthly users, 97.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.01 / actor start

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?

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 User Search

> Who ranks for a keyword on Instagram — and how big those accounts are.

### ✨ What you get

One dataset row per account hit:

| Field | What it is |
|---|---|
| **`searchPosition`** | **Instagram's own rank for this keyword** — 0 is the top result |
| `keyword` | which keyword produced the hit |
| `username` / `userId` / `fullName` | the account |
| `isVerified` / `isPrivate` / `profilePicUrl` / `profileUrl` | qualification and links |
| `followers` / `following` / `posts` / `biography` / `externalUrl` | populated when enrichment ran, otherwise `null` |
| `enriched` / `postsCountReliable` | whether counts were looked up, and whether the post count can be trusted |

The run summary gives, per keyword: result count, how many were enriched, verified/private counts, the median follower count of enriched rows, and the **top 5 hits in Instagram's order**.

### 💼 Use cases

- **Finding who owns a keyword** — `searchPosition` is Instagram's own rank, 0 being the top result, and the Actor never re-sorts it by size. Reading position 0, 1, 2 tells you which account a term belongs to.
- **Tracking a competitor's movement on your terms** — run the same keywords weekly and diff `searchPosition`. An account that moves from 7 to 3 over a month is winning ground you thought was yours.
- **Sizing the accounts you found** — `enrichTop` (default 20, max 30) resolves follower counts on the top hits per keyword, so a keyword ranking is a list of mega and micro accounts mixed together until you check the numbers.
- **Cross-checking overlap across terms** — the same account found for several keywords appears once per keyword, each with its own position. An account ranking for three of your five terms is the one worth briefing.

### ✅ Who this is for

- **SEO and social SEO managers**— watching where accounts rank for a set of niche terms and whether that is moving.
- **Content strategists**— scoping a keyword before commissioning content, who need to know whether the accounts already ranking are brands or creators.
- **Agencies running competitor keyword sweeps**— across up to 20 terms who need an ordered account list rather than a screenshot of search results.
- **Analysts building a prospect list by search term**— who will chain the top hits into the profile or posts Actor for the deeper read.

### ❌ Who this is NOT for

- **Ranking posts or Reels** — this returns accounts, one row per hit. For what is ranking *inside* a term, use the Instagram Reels Search Actor; for what is under a tag, the Instagram Hashtag Posts Actor.
- **A historical rank tracker** — `searchPosition` is a snapshot of this run, not a stored history. Trend data only exists once you schedule the Actor and diff the column yourself.
- **Reading `followers: null` as zero** — only the first `enrichTop` hits per keyword are looked up; the rest keep `null` rather than a misleading zero, and `enriched` marks which rows have real numbers. `enrichTop: 0` gives you handles with no sizes at all.
- **Trusting `posts: 0`** — Instagram sometimes reports 0 for accounts that clearly have posts. `postsCountReliable` flags those rows; ignore the number when it is false.
- **A full account directory or another platform** — typically around 50 accounts per keyword is the full list Instagram's account search returns, and there is no pagination beyond it. TikTok, YouTube, Google Business or GMB listings are different products with different data.

### 🚀 Quick start

1. Open the Actor and press **Start** (defaults to the keyword `yoga`).
2. Add your niche keywords — one per line, up to 20.
3. Sort by `searchPosition` to see who owns the keyword; use `enrichTop` to size them up.

### 📥 Input parameters

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `keywords` | list | `yoga` | Keywords to search accounts for, one per line, up to 20 per run. |
| `enrichTop` | number | `20` | How many hits per keyword get a follower-count lookup (0–30). Set `0` for the fastest run. |

### 📤 Output

- **Dataset** — one row per account hit (or a notice when nothing was collected)
- **SUMMARY** — per-keyword top hits and medians, request counts and warnings

### ⚙️ How it works

1. Each keyword is sent to Instagram's account search; every hit keeps its `position` — that ordering is the data, so it is never re-sorted by size.
2. The first `enrichTop` hits per keyword get a profile lookup, which adds followers/posts/bio.
3. The same account found for several keywords appears once per keyword, each with its own position — that is what makes competitor tracking possible.

### 💰 Billing

Pay per result — you are charged for the account rows this Actor actually returns, not for the run. Cost has two parts and both are visible in the summary: one search per keyword, plus one enrichment lookup per enriched hit. Lower `enrichTop` to spend less. Free tier: 5 runs/day.

### ❓ FAQ

**What does searchPosition mean?**
The order Instagram itself returned for that keyword in this run. Position 0 is the first result. It is a snapshot, not a historical rank — run it weekly to see movement.

**Why are followers null on many rows?**
Only the first `enrichTop` hits per keyword are looked up. The rest keep `null` rather than a misleading zero, and `enriched` tells you which rows have real numbers.

**Can I track how my ranking changes over time?**
Yes: run the same keywords on a schedule and diff the `searchPosition` column over time. Nothing extra is needed — the Actor never re-sorts that column.

**Are the post counts reliable?**
Check `postsCountReliable`. Instagram sometimes reports 0 posts for accounts that have them, and the flag marks those rows.

**How many results come back per keyword?**
Typically around 50 accounts per keyword, which is the full list Instagram's search returns for accounts.

### 📚 Resources

- Apify free tier: 5 runs/day, then upgrade

# Changelog

This Actor's version history is a separate document: https://apify.com/opspilot.cc/instagram-user-search/changelog.md

# Actor input Schema

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

One keyword per line, up to 20 per run. Each keyword returns the accounts Instagram ranks for it.

## `enrichTop` (type: `integer`):

How many hits per keyword get a follower-count lookup. Set 0 for the fastest run — rows then have no follower numbers.

## Actor input object example

```json
{
  "keywords": [
    "yoga"
  ],
  "enrichTop": 20
}
```

# Actor output Schema

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

One row per account hit, or a single notice when nothing was collected.

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

Per-keyword result counts, top hits, median followers, request counts and warnings.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("opspilot.cc/instagram-user-search").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("opspilot.cc/instagram-user-search").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 '{}' |
apify call opspilot.cc/instagram-user-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,opspilot.cc/instagram-user-search"
        }
    }
}
```

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/ZhFLeJFdrs07JdckS/builds/1AzSnIng40da5fRdg/openapi.json