Skip to navigation

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

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 resultDecisionWhat the note must explain
Two dated coffee tutorials fit the brief; one is within the review windowshortlistCite 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 checkedholdState 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 subjectrejectCite the mismatch with the brief. Do not label the person a fake creator.
The returned account is the seedseed referenceKeep 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

NeedRouteContinue with
Creator candidates with available profile datadata:creator.discoverBilled by delivered creator; review content and missing information after export
Platform-recommended account identitiesdata:instagram.v2.fetch_similar_usersBilled 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

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

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

EvidenceHow to use it
handle, profile_url, bioOpen the actual profile and check subject, language and current activity.
followers, posts_countCompare scale and posting history; neither field proves audience quality.
engagement_rate_pct, avg_likesRetain nulls as unknown. Do not substitute zero or compare missing values as poor performance.
email, has_emailA discovered address is a lead to review, not verified ownership or permission to send.
Contact provenance, when returnedCheck whether an address belongs to the creator or a linked brand. Missing provenance remains unverified.

The Social Data guide 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.

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.

{"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.

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:

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.