> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# How do I build an Instagram creator shortlist with content evidence?

> Define the collaboration brief, discover candidates from a seed and review recent content, evidence and open questions before selecting a shortlist.

To find Instagram creators similar to an account that already fits your product, write the collaboration brief first, then discover candidates from the seed account with `creator.discover` (billed per delivered creator) or `instagram.v2.fetch_similar_users` (billed per request). Export the saved response to a review sheet with `creator_sheet.py` or `similar_sheet.py`, inspect each candidate's recent work and record a specific selection reason. The returned account list starts the review; the shortlist comes from the review.

The example brief below uses English-language home-coffee content. Adapt the brief to your product, and keep actual content evidence for every shortlisted candidate.

## Define evidence-based selection criteria first

For a concrete brief, suppose you need **up to three English-language home-coffee creators** to review before outreach. Set the criteria before reading the results. The brief below is an example, not an assessment of any real account:

* Required: recent public content shows home-coffee preparation; record two relevant post URLs, their dates and the observed fit. English-language content is a content criterion, not proof of the audience's country.
* Required: at least one relevant post within your chosen last-30-days window, counted back from the documented review date. A returned `posts_count` is lifetime volume, not evidence of recent activity.
* Preferred: 10,000–100,000 reported followers. The follower range is a campaign choice, not an API quality threshold. A missing follower count sends the candidate to further review, not to zero or automatic rejection.
* Not required at this stage: a discovered email. Missing contact details do not exclude an otherwise suitable creator, and a found email is not consent to message the creator. Rates and availability are separate checks.

Keep the original exported CSV unchanged. In a review copy, fill the existing `fit_reason` and `checks_needed` columns and add your own `evidence_urls`, `reviewed_at` and `reviewer` columns. The added columns are human research notes, not returned API fields. Keep the original identity and request ID so a teammate can trace each decision. Do not copy a promoted brand's address into the creator's verified-contact field.

| Illustrative review result                                                | Decision       | What the note must explain                                                                                                           |
| ------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Two dated coffee tutorials fit the brief; one is within the review window | shortlist      | Cite the two actual posts and the review date. A shortlist decision approves further partnership review, not a contract or outreach. |
| Bio mentions coffee but recent posts could not be checked                 | hold           | State the missing content evidence and the next check. Do not certify current activity from the bio or the total post count.         |
| Reviewed recent posts focus on an unrelated subject                       | reject         | Cite the mismatch with the brief. Do not label the person a fake creator.                                                            |
| The returned account is the seed                                          | seed reference | Keep the seed row as context, separate from newly discovered candidates.                                                             |

Deliver the original response and request ID, the unedited exported CSV, the completed review copy and a short decision note. Report returned rows, unique candidates, seed rows, shortlisted, held and rejected accounts, and unresolved identities as separate counts, counting each reviewed candidate once. If one candidate is shortlisted, one held and one rejected, write exactly that, not “three qualified creators.” A review with no qualifying candidate is a valid outcome and does not authorize another paid search.

For repeat campaigns, store the brief and the review date with each review copy. Recheck the cited profile and posts before contacting anyone; a months-old `has_email` or engagement number is not current verification. The workflow ends at an evidence-backed review sheet and sends no message.

## Choose the discovery route

| Need                                           | Route                                   | Continue with                                                                        |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
| Creator candidates with available profile data | `data:creator.discover`                 | Billed by delivered creator; review content and missing information after export     |
| Platform-recommended account identities        | `data:instagram.v2.fetch_similar_users` | Billed by request; inspect profiles and content before any additional data retrieval |

Choose one route, and reuse saved responses when available. The sections below give the request and the local review-sheet export for each route.

## Choose a useful seed

Use the handle or profile URL of an account you have already reviewed. Write down why the seed fits: subject matter, language, audience and content format. A large but irrelevant celebrity seed answers a different question from finding relevant niche creators.

The current `creator.discover` contract supports `platform: instagram`. Do not send TikTok or YouTube and assume the same similarity lookup exists there.

## Inspect the contract and billing unit

```bash
curl -sS https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:creator.discover"}'
```

The `/v1/capabilities/inspect` call above is free. In the response, check `pricing.unit`, not only the amount: `creator.discover` is billed per creator, unlike request-billed social actions. The documented `limit` range is 1–6, and `limit` sets how many related creators to request. The seed can come back as an additional row, so `limit: 3` is not a three-row billing ceiling.

### Estimate cost by the delivery unit

Use the current [pricing page](https://beatapi.io/pricing). `creator.discover` bills each delivered creator entry: `limit:3` requests three similar candidates, and the seed may come back as an additional row, so include the seed row in the estimate. A successful empty result is billed at the one-unit minimum. Local deduplication and selection do not change the delivered-entry charge.

## Request a small first batch

After approving the price and billing unit, replace `<seed_handle>` with the chosen seed account:

```bash
mkdir creator-query && \
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"creator.discover","params":{"platform":"instagram","seed":"<seed_handle>","limit":3}}' \
  -D creator-query/response.headers \
  -o creator-query/instagram-creator-candidates.json
```

Check the response `status` before treating the response as a successful discovery. The published output schema puts the candidates in an array at `data`; fields may be missing or null. If the seed itself comes back, identify the seed row by the returned identity and `discovered_via`, and do not count the seed as a new candidate.

## Review the records, not just a score

| Evidence                           | How to use it                                                                                             |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `handle`, `profile_url`, `bio`     | Open the actual profile and check subject, language and current activity.                                 |
| `followers`, `posts_count`         | Compare scale and posting history; neither field proves audience quality.                                 |
| `engagement_rate_pct`, `avg_likes` | Retain nulls as unknown. Do not substitute zero or compare missing values as poor performance.            |
| `email`, `has_email`               | A discovered address is a lead to review, not verified ownership or permission to send.                   |
| Contact provenance, when returned  | Check whether an address belongs to the creator or a linked brand. Missing provenance remains unverified. |

The [Social Data guide](https://docs.beatapi.io/social-data) explains that an address on a linked website may belong to a brand the creator promotes, so do not treat such an address as a personal contact. Do not use a single ranking score as evidence of authentic followers, brand safety or buying intent.

Write the selection reason at the post level. For example, “Two recent videos show walking in the rain, which fits a commuter-shoe trial,” with links. If another creator has only indoor runway footage, record “Need an outdoor wear example.” Use the contact column for public details you have checked.

## Produce a decision sheet

Keep one row per returned candidate: profile, reason for fit, the audience figures actually returned, contact evidence, unresolved checks and a decision such as review, hold or reject. Record your campaign constraints separately so another teammate can reproduce each decision.

Check recent content and campaign fit manually. `creator.discover` does not establish pricing, sponsorship availability or audience geography; leave those fields unknown until a source supports them.

Do not run a second contacts lookup for records that already include the needed information. Each additional lookup is a separate task with its own cost and approval.

## Brief an agent with a bounded assignment

> Use the Instagram account I provide as a seed for up to three similar creators. Inspect creator.discover first and explain its per-creator billing, including empty-result rules. After approval, run discovery once. Build a shortlist with profile links, evidence of fit and explicitly unknown fields. Do not claim an email is verified, infer audience authenticity from a score, send messages or enrich more accounts without asking.

## What the workflow delivers

The deliverable is a reviewed candidate list with reasons and open questions, not an outreach campaign. Save the original response and request ID so later reviews can tell returned facts from human judgments. Public profile information can change, so recheck each profile before outreach.

Sources: the published `creator.discover` and `instagram.v2.fetch_similar_users` contracts; the examples on this page are not results of a paid discovery.

## Export the saved discovery into a review sheet

Save the script below as `creator_sheet.py` and run `python3 creator_sheet.py creator-query/instagram-creator-candidates.json <original_seed_handle> creator-review`. `creator_sheet.py` makes no network requests. `creators.csv` keeps a stable identity, missing values, source provenance and an identifiable seed row. Contact information is always marked `not_verified`, and the script performs no outreach. Identical duplicates collapse into one row; conflicting records stop processing. An existing output directory is never overwritten.

Fill `fit_reason` and `checks_needed` after reviewing actual content, then decide hold, reject or shortlist. The default `review` label is not approval. Keep the original query time and parameters with the raw response. An empty result produces headers and zero-candidate coverage; an empty result is still a billed query.

```python
import csv
import json
import sys
from decimal import Decimal, InvalidOperation
from pathlib import Path
from urllib.parse import urlsplit

source, seed, output = sys.argv[1:]
def handle(value):
    value = value.strip()
    if "://" in value:
        url = urlsplit(value)
        if url.hostname not in ("instagram.com", "www.instagram.com"):
            raise SystemExit("Use an Instagram seed profile")
        value = url.path.strip("/")
    value = value.lstrip("@").lower()
    if not value or "/" in value or any(not (c.isalnum() or c in "._") for c in value):
        raise SystemExit("Use the original seed handle or profile URL")
    return value
seed_handle = handle(seed)
raw = json.loads(Path(source).read_text(encoding="utf-8"))
if raw.get("status") != "succeeded" or raw.get("action") != "creator.discover" or not raw.get("request_id"):
    raise SystemExit("Expected successful creator.discover with request provenance")
items = raw.get("data")
if not isinstance(items, list):
    raise SystemExit("Expected the published data array")
def metric(value, integer=False):
    if value is None:
        return ""
    try:
        if isinstance(value, bool):
            raise InvalidOperation
        n = Decimal(str(value))
        if not n.is_finite() or n < 0 or (integer and n != n.to_integral_value()):
            raise InvalidOperation
        return int(n) if integer else str(n)
    except InvalidOperation:
        raise SystemExit("Invalid numeric metric")
rows, seen, duplicates = [], {}, 0
for item in items:
    if not isinstance(item, dict) or item.get("platform") not in (None, "instagram"):
        raise SystemExit("Unexpected creator record/platform")
    normalized = handle(item["handle"]) if item.get("handle") else ""
    profile_handle = handle(item["profile_url"]) if item.get("profile_url") else ""
    if normalized and profile_handle and normalized != profile_handle:
        raise SystemExit("Creator handle and profile URL identify different accounts")
    normalized = normalized or profile_handle
    user_id = item.get("user_id")
    if user_id is not None and not isinstance(user_id, str):
        raise SystemExit("Preserve platform user IDs as strings")
    aliases = (["id:" + user_id] if user_id else []) + (["handle:" + normalized] if normalized else [])
    if not aliases:
        raise SystemExit("No stable creator identity")
    previous = [seen[key] for key in aliases if key in seen]
    if previous:
        if any(record != item for record in previous):
            raise SystemExit("Conflicting duplicate creator records")
        duplicates += 1
        continue
    for key in aliases:
        seen[key] = item
    is_seed = normalized == seed_handle if normalized else None
    email = item.get("email")
    if email is not None and not isinstance(email, str):
        raise SystemExit("Unexpected email field type")
    row = {"user_id": user_id or "", "handle": item.get("handle"), "name": item.get("name"),
           "profile_url": item.get("profile_url"), "bio": item.get("bio"),
           "followers": metric(item.get("followers"), True), "posts_count": metric(item.get("posts_count"), True),
           "engagement_rate_pct": metric(item.get("engagement_rate_pct")), "avg_likes": metric(item.get("avg_likes")),
           "email": email, "has_email_reported": item.get("has_email"), "contact_verification": "not_verified",
           "discovered_via": item.get("discovered_via"), "is_seed": is_seed,
           "decision": "identity_review" if is_seed is None else ("seed_reference" if is_seed else "review"), "fit_reason": "", "checks_needed": "",
           "source_file": source, "request_id": raw["request_id"]}
    rows.append(row)
folder = Path(output)
folder.mkdir(exist_ok=False)
columns = ["user_id", "handle", "name", "profile_url", "bio", "followers", "posts_count", "engagement_rate_pct", "avg_likes", "email", "has_email_reported", "contact_verification", "discovered_via", "is_seed", "decision", "fit_reason", "checks_needed", "source_file", "request_id"]
with (folder / "creators.csv").open("x", encoding="utf-8-sig", newline="") as file:
    writer = csv.DictWriter(file, fieldnames=columns)
    writer.writeheader()
    for row in rows:
        writer.writerow({k: ("'" + v if isinstance(v, str) and v.lstrip().startswith(("=", "+", "-", "@")) else v) for k, v in row.items()})
(folder / "coverage.json").write_text(json.dumps({"returned_records": len(items), "unique_records": len(rows),
    "duplicate_records": duplicates, "identified_seed_records": sum(v["is_seed"] is True for v in rows),
    "review_candidates": sum(v["is_seed"] is False for v in rows), "unresolved_seed_identity": sum(v["is_seed"] is None for v in rows), "emails_verified": 0, "messages_sent": 0,
    "scope": "candidate discovery, not audience authenticity or campaign performance proof"}, indent=2), encoding="utf-8")
```

## Alternative: review platform-suggested similar accounts without enrichment

If you only need a small list of account identities with privacy and verification flags, use `instagram.v2.fetch_similar_users`, a separate request-billed action that accepts `username` or `user_id`. `instagram.v2.fetch_similar_users` does not return the `creator.discover` metrics or contact enrichment described above. Inspect the action first and choose one route instead of paying for both. The returned `count` is not the seed's follower count, and the action has no next-page input.

```json
{"action":"instagram.v2.fetch_similar_users","params":{"username":"<reviewed_seed_username>"}}
```

Save the successful original response as `instagram-similar.json`. `similar_sheet.py` below reads the verified `data.data.items` path into a manual review sheet. The script requires a returned ID and username for each traceable row, keeps unknown flags blank, marks the seed and rejects conflicting identities. `similar_sheet.py` has no network access and no follow or contact action.

```python
import csv
import json
import re
import sys
from pathlib import Path

source, seed, output = sys.argv[1:4]
if not re.fullmatch(r"[A-Za-z0-9_.]+", seed):
    raise SystemExit("Use the original plain seed username, not a URL or display name.")
raw = json.loads(Path(source).read_text(encoding="utf-8"))
if raw.get("status") != "succeeded" or raw.get("action") != "instagram.v2.fetch_similar_users":
    raise SystemExit("Expected successful Instagram similar-users response.")
request_id = raw.get("request_id")
if not isinstance(request_id, str) or not request_id.strip():
    raise SystemExit("Missing request_id.")
items = raw.get("data", {}).get("data", {}).get("items")
if not isinstance(items, list):
    raise SystemExit("Expected data.data.items array.")
rows, by_id, by_handle = [], {}, {}
duplicates = 0
for item in items:
    if not isinstance(item, dict):
        raise SystemExit("Candidate must be an object.")
    uid, handle = item.get("id"), item.get("username")
    if not isinstance(uid, str) or not uid.strip() or uid != uid.strip() or uid in {"[redacted]", "[redacted-depth]"} or not isinstance(handle, str) or not re.fullmatch(r"[A-Za-z0-9_.]+", handle):
        raise SystemExit("Candidate needs a returned user ID and valid username; keep the raw file for review.")
    name = item.get("full_name")
    if name is not None and not isinstance(name, str):
        raise SystemExit("Invalid display name.")
    flags = [item.get("is_private"), item.get("is_verified")]
    if any(value is not None and type(value) is not bool for value in flags):
        raise SystemExit("Account flags must be booleans or absent.")
    identity = handle.lower()
    comparable = [identity, name, *flags]
    if uid in by_id:
        if by_id[uid] != comparable:
            raise SystemExit("Conflicting observations for the same user ID.")
        duplicates += 1
        continue
    if identity in by_handle and by_handle[identity] != uid:
        raise SystemExit("Same username is associated with conflicting user IDs.")
    by_id[uid] = comparable
    by_handle[identity] = uid
    rows.append({"user_id": uid, "username": handle, "display_name": name,
                 "profile_url": f"https://www.instagram.com/{handle}/", "is_private": flags[0],
                 "is_verified": flags[1], "seed_username": seed, "is_seed": identity == seed.lower(),
                 "decision": "exclude_seed" if identity == seed.lower() else "review",
                 "fit_reason": "", "checks_needed": "", "source_file": source, "request_id": request_id})
folder = Path(output)
folder.mkdir(exist_ok=False)
columns = ["user_id", "username", "display_name", "profile_url", "is_private", "is_verified", "seed_username", "is_seed", "decision", "fit_reason", "checks_needed", "source_file", "request_id"]
with (folder / "similar-accounts.csv").open("x", encoding="utf-8-sig", newline="") as file:
    writer = csv.DictWriter(file, fieldnames=columns)
    writer.writeheader()
    for row in rows:
        writer.writerow({key: ("'" + value if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")) else value) for key, value in row.items()})
(folder / "coverage.json").write_text(json.dumps({"returned_records": len(items), "unique_accounts": len(rows), "duplicates": duplicates,
    "seed_accounts": sum(row["is_seed"] for row in rows), "messages_sent": 0,
    "scope": "similarity recommendations, not followers, audience verification or verified contacts"}, indent=2), encoding="utf-8")
```

Pass the plain username actually sent in the `instagram.v2.fetch_similar_users` request, without `@` or a profile URL:

```bash
python3 similar_sheet.py instagram-similar.json '<reviewed_seed_username>' similar-review
```

Review each candidate's profile content and fill `decision`, `fit_reason` and `checks_needed`. A private account is not automatically a bad candidate, but the row gives no access to the account's private content. A verification badge is not audience-quality evidence. Missing contact or audience fields are not zero; `instagram.v2.fetch_similar_users` does not supply them. Request additional details only for selected candidates, within a separate budget.