API Reference

Search creators, unlock contact details, export and organise lists from your own code. Base URL https://creatorlookup.com/api/v1. Machine-readable: openapi.json · api.md (paste into Claude or ChatGPT).

Checking for your API key…

Overview

The Creator Lookup API gives your code the same creator search, unlocks, exports and lists you use in the app, on your own account and credits.

Base URL: https://creatorlookup.com/api/v1
Every endpoint is POST https://creatorlookup.com/api/v1/{endpoint} with a JSON body and a JSON response.
Endpoints are named after actions (search_creators, run_export, …). They are the same tools our MCP server gives AI assistants, so behaviour, limits and pricing are identical across the API, MCP and the app's AI chat.
Machine-readable spec: openapi.json. Whole reference as one Markdown file for AI assistants: /docs/api.md.

Authentication

Find your API key in the app under Settings → MCP & API (open). Send it on every request:

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY works too.

API access needs an active paid plan (AppSumo plans included) or a positive credit balance. Otherwise requests get 403 api_access_requires_plan.
The key acts as your account: anything it does (searches, unlocks, exports) is charged to your credits and shows up in your history. Keep it on your server. Do not put it in browser or mobile app code.
Need a new key? Contact support and we will rotate it; the old one stops working at once.

Quickstart

Check your key and balance:

curl -X POST https://creatorlookup.com/api/v1/get_credit_balance \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Search. Only basic.platform is required:

curl -X POST https://creatorlookup.com/api/v1/search_creators \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"basic":{"platform":"instagram"},"creator":{"audienceRange":{"minValue":10000,"maxValue":100000}},"content":{"bioKeywords":{"any":["skincare"]}}}'

Get contact details. Either export the top N of that search with run_export (pass the response's filters_used as filters), or unlock hand-picked handles with unlock_creators. Both run in the background and return an id.
Poll get_history_data with that id until status is complete, then page through the rows (emails included).

Credits and limits

Credits are shared with your account in the app. Rate limits are per account, across the API, MCP and the app (full limits).

What	Cost
Search results (`search_creators`)	First 75 creators returned per UTC day free (API and MCP together). After that, 1 credit per 4 creators if usage-based pricing is on (Settings → MCP & API); if it is off, searches return 402 until 00:00 UTC.
Unlock or look up a creator	1 credit per creator you don't already own. Owned creators are free.
Export (`run_export`)	Up to 1 credit per creator exported; already-owned creators are free. The balance must cover `limit` up front.
Reading results, lists, history, posts, filter values, balance	Free

Limit	Value
Searches	20 per minute
Live profile and post fetches	60 per hour, 300 per day (paid)
Exports	5 per minute, 40 per hour, 200 per day
Unlocks	30 per minute, 1,500 per day
Creators per search page	10 (page with `offset`, up to 500 per search)
Creators per `get_history_data` call	500
Creators per export	10,000
Handles per `unlock_creators` call	25

Hitting a limit returns 429 with a Retry-After header when we know when to retry. Per-minute and per-hour limits are rolling; daily limits reset at 00:00 UTC. Need more? Email jose@creatorlookup.com.

Responses and errors

Successful responses are 200 with the endpoint's JSON. Many responses carry a status field; the HTTP status code follows it:

HTTP	`status`	Meaning
200	ok, complete, processing, empty, unavailable, or none	Success. `processing` means a background job is still running.
400	invalid_request	The body failed validation. `errors` lists each field and problem.
400	needs_confirmation	`confirmed: true` was missing on a credit-spending call. Nothing ran.
401	unauthorized	Missing or invalid API key.
402	usage_pricing_required	Today's free API creators are used up and usage-based pricing is off.
402	insufficient_credits	Not enough credits. `topup_url` / `purchase_url` says where to buy more.
403	api_access_requires_plan, account_suspended	The account cannot use the API.
404	not_found	Unknown endpoint, or the list/item does not exist.
422	error	The request was valid but could not be done (for example a private profile). `message` explains.
429	rate_limited	Too many requests. See `Retry-After` / `retry_after`.
500	error	Our fault. Safe to retry reads; check history before retrying exports.

Error bodies always have status and a human-readable message. Some responses include suggested_next: a plain-English hint written for AI agents. Your code can ignore it.

Background jobs

run_export and unlock_creators return immediately with an id (export_id / history_id) and keep working in the background. To get the results:

Call get_history_data with {"history_id": "<id>"} every 30-60 seconds.
While it returns status: "processing", wait and try again. Most jobs finish in 1-3 minutes.
When status is complete, read creators. If has_more is true, call again with offset increased by returned.

Don't retry a run_export or unlock_creators call just because it is slow: check list_search_history first, or you may start the job twice.

Data use and compliance

Creator data comes from public profiles. When you store, display or contact creators using data from this API, you are responsible for doing so lawfully, including under GDPR, CCPA/CPRA, CAN-SPAM and the platforms' own rules: have a lawful basis, honour opt-outs and deletion requests, and don't use the data for spam or anything unlawful.

Data is provided as-is under our Terms of Service. Creator Lookup is not responsible for how you or your users use it. Follower counts, emails and other details change; refresh records you rely on rather than storing them indefinitely.

Building with AI assistants

Point Claude, ChatGPT or Cursor at https://creatorlookup.com/docs/api.md (the full reference in one file) or at the OpenAPI spec and ask it to write the integration.

If you want an assistant to use Creator Lookup directly instead of writing code, connect our MCP server: MCP setup.

Search creators

POST/api/v1/search_creators

The core discovery call. Send a filter object (platform is the only required field) and get back the total number of matching creators plus a page of up to 10 creators with name, handle, followers, engagement, bio and location.

Page through the same search with offset (0, 10, 20, … up to 490). Each response gives the next offset in next_offset.

Searches do not return contact details. To get emails, either export the top N of a search (run_export) or unlock specific handles (unlock_creators / lookup_creator), then read the rows with get_history_data.

Tips: bio keywords (content.bioKeywords.any) are the most reliable niche filter on Instagram and TikTok. basic.contactDetails defaults to ["EMAIL"]; send [] to include creators without a public email. Location and language accept plain names ({"name": "Germany"}) or ids from search_locations / search_languages.

Cost: Free for the first 75 creators returned per UTC day (API and MCP together). After that, 1 credit per 4 creators returned if usage-based pricing is on, otherwise 402 until 00:00 UTC.

Request body

Field	Type	Description
`basic`required	object	Required. Platform, contact requirement and sort order.
`basic.platform`required in parent	string	Which network to search. One platform per search.one of: instagram, youtube, tiktok
`basic.contactDetails`	string[]	Only return creators who list ALL of these contact channels. Defaults to ["EMAIL"] when omitted; pass [] to include creators without a public email (a much larger pool). 26 allowed values `EMAILPHONELINKTREEBBMKIKSKYPEWHATSAPPWECHATTELEGRAMVIBERINSTAGRAMYOUTUBETIKTOKTWITTERSNAPCHATFACEBOOKWEIBOITUNESKAKAOPINTERESTLINEIDTWITCHTVSARAHAHSAYATTUMBLRVK`
`basic.sortBy`	string	Result order (descending). Defaults to FOLLOWER_COUNT. Common: FOLLOWER_COUNT, ENGAGEMENT_RATE, AVERAGE_VIEWS, AVERAGE_LIKES, FOLLOWER_GROWTH. Some values only apply to some platforms. 24 allowed values `DESCRIPTIONAVERAGE_LIKEAVERAGE_LIKESAUDIENCE_LOCATIONAUDIENCE_LOCATIONSAUDIENCE_LANGUAGEAUDIENCE_AGEAUDIENCE_INTERESTSAUDIENCE_LOOKALIKESAUDIENCE_BRAND_AFFINITIESFOLLOWER_COUNTFOLLOWER_GROWTHAIRTIMEENGAGEMENT_RATETOPIC_RELEVANCEAVERAGE_VIEWSREELS_VIEWSPEAK_VIEWERSAVG_CONCURRENT_VIEWERSTOTAL_VIEWS_GROWTHTOTAL_LIKES_GROWTHHOURS_WATCHEDCREATOR_LOOKALIKESCONTENT_COUNT`
`creator`	object	Filters on the creator themself: size, location, language, demographics.
`creator.audienceRange`	object	Follower (subscriber) count range, e.g. {minValue: 10000, maxValue: 100000} for micro creators.
`creator.audienceRange.minValue`	number	Inclusive lower bound. Omit for no minimum.
`creator.audienceRange.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`creator.location`	object	Where the CREATOR is based.send one of: {id, display_name?} or {name}
`creator.location.id`	string	Location id from search_locations.form A, required in that form
`creator.location.display_name`	string	form A
`creator.location.name`	string	Plain place name, e.g. "United States", "California", "London". Resolved to the best match.form B, required in that form
`creator.language`	object	The language the creator posts in.send one of: {code, name?} or {name}
`creator.language.code`	string	ISO 639-1 language code from search_languages, e.g. "en".form A, required in that form
`creator.language.name`	string	form A
`creator.language.name`	string	Language name, e.g. "Spanish". Resolved to its code.form B, required in that form
`creator.gender`	object	The creator's gender.
`creator.gender.code`required in parent	string	one of: MALE, FEMALE
`creator.age`	object	The creator's age in years.
`creator.age.minValue`	number	Inclusive lower bound. Omit for no minimum.
`creator.age.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`creator.verified`	object	{value: true} for verified (blue check) accounts only.
`creator.verified.value`required in parent	boolean
`creator.interests`	object	Instagram only. Interest names from search_interests, e.g. ["Fitness & Yoga"]. Ignored on other platforms.
`creator.interests.values`required in parent	string[]
`creator.accountType`	object	Instagram only. Any of PERSONAL, BUSINESS, CREATOR. Ignored on other platforms.
`creator.accountType.types`required in parent	string[]
`creator.lookalikeCreators`	string	Platform lookalike filter: a seed creator's username without the @.
`audience`	object	Filters on the creator's followers (audience demographics).
`audience.location`	object	Where the creator's AUDIENCE (followers) is located.
`audience.location.id`	string	Location id from search_locations.
`audience.location.name`	string	Plain place name, e.g. "Germany". Give id or name.
`audience.location.percentage`	number	At least this percent (0-100) of the creator's audience must match.min 0max 100
`audience.age`	object	The audience's age band.
`audience.age.minValue`	number	Youngest age in the band, in years.
`audience.age.maxValue`	number	Oldest age in the band, in years.
`audience.age.percentage`	number	At least this percent (0-100) of the audience is in the band.min 0max 100
`audience.gender`	object	The audience's gender split.
`audience.gender.code`required in parent	string	one of: MALE, FEMALE
`audience.gender.percentage`	number	At least this percent (0-100) of the creator's audience must match.min 0max 100
`audience.language`	object	The language the audience speaks.
`audience.language.code`	string	ISO 639-1 code from search_languages.
`audience.language.name`	string	Language name. Give code or name.
`audience.language.percentage`	number	At least this percent (0-100) of the creator's audience must match.min 0max 100
`audience.audienceLookalike`	string	Username (no @) of a creator whose audience the results' audiences should resemble.
`audience.audienceCredibilityScore`	number	Minimum share of real (non-bot) followers, 0-1. E.g. 0.8 = at least 80% credible followers.min 0max 1
`content`	object	Filters on what the creator writes and posts: bio, captions, hashtags, topics, recency.
`content.bioKeywords`	object	Keywords matched against the profile bio. A multi-word entry matches bios containing all of its words, in any order. Example: {any: ["skincare", "esthetician"], none: ["agency"]}.
`content.bioKeywords.any`	string[]	Bio contains at least one of these. The best niche filter on Instagram/TikTok.
`content.bioKeywords.all`	string[]	Bio must also contain every one of these.
`content.bioKeywords.none`	string[]	Bio contains none of these.
`content.captionKeywords`	object	Words used in recent post captions. Narrows the pool sharply on Instagram/TikTok; add it after bio keywords if needed.
`content.captionKeywords.keywords`required in parent	string[]
`content.hashtags`	string[]	Instagram and TikTok only. Hashtags without the #, e.g. ["skincareroutine"].
`content.mostRecentPosts`	string \| null	Only creators who posted on or after this date (YYYY-MM-DD). Use to exclude inactive accounts.
`content.topics`	string[]	Content topics from search_topics, e.g. ["gaming"]. Works best on YouTube.
`content.minPostCount`	integer	Minimum number of posts on the account.min 0max 9007199254740991
`content.maxPostCount`	integer	Maximum number of posts on the account.min 0max 9007199254740991
`performance`	object	Filters on engagement and growth.
`performance.averageLikes`	object	Average likes per post.
`performance.averageLikes.minValue`	number	Inclusive lower bound. Omit for no minimum.
`performance.averageLikes.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`performance.averageViews`	object	Average views per video/reel.
`performance.averageViews.minValue`	number	Inclusive lower bound. Omit for no minimum.
`performance.averageViews.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`performance.engagementRate`	object	Engagement rate in PERCENT, e.g. {minValue: 3} = at least 3%. (Search results report it as engagement_rate_pct, same unit.)
`performance.engagementRate.minValue`	number	Inclusive lower bound. Omit for no minimum.
`performance.engagementRate.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`performance.audienceGrowth`	object	Fast-growing creators: grew at least `percentage`% in the last `interval` months.
`performance.audienceGrowth.interval`	number	Lookback window in months, 1-6.
`performance.audienceGrowth.percentage`	number	Minimum follower growth in percent over that window.
`page_request_id`	string	Use the page_request_id from the previous result for the next paid page; preserve it on retries.format: uuid
`offset`	integer	Pagination into the match set: pass 10 to "see 10 more", 20 for the next page, etc. What a page costs is in each result's suggested_next — tell the user before paging.default: 0min 0max 490

Response

Field	Type	Description
`total`	number	Total creators matching the filters (not just this page).
`preview_creators`	object[]	This page: up to 10 creators, in sort order.
`preview_creators[].name`	string	Display name.
`preview_creators[].handle`	string	Username without the @. Pass this to lookup_creator, unlock_creators, get_creator_posts.
`preview_creators[].platform`	string	instagram, tiktok or youtube.
`preview_creators[].follower_count`	number	Followers (subscribers on YouTube).
`preview_creators[].engagement_rate_pct`	number \| null	Engagement rate in percent: 4.5 means 4.5%. Null when unknown.
`preview_creators[].bio`	string \| null	Profile bio, truncated to about 160 characters.
`preview_creators[].location`	string \| null	Where the creator is based, when known.
`preview_creators[].is_verified`	boolean	Platform verification badge.
`preview_creators[].profile_url`	string \| null	Link to the profile on the platform.
`preview_creators[].photo_url`	string \| null	Profile picture URL. Platform CDN links expire after a few days; do not store them long-term.
`filters_used`	object (map)	The filters after defaults were applied. Pass this object as `filters` to run_export to export this exact search.
`filters_summary`	string	Human-readable one-liner of the applied filters.
`offset`	number	Offset of this page.
`next_offset`	number	Offset to request for the next page.
`page_request_id`	string	Opaque id for this page. Not needed for API calls.
`credits_remaining`	number	Account credit balance after this call.
`estimated_cost_per_creator`	number	Credits per creator for an export (currently 1).
`max_affordable_count`	number	How many creators the current balance could export.
`source`	string	Channel the search was recorded under.
`usage`	object	This account's daily API/MCP allowance, as of this call.
`usage.free_creators_per_day`	number	Free creators per UTC day across API and MCP (currently 75).
`usage.free_creators_left`	number	Free creators left today after this call.
`usage.creators_per_credit`	number	Past the free allowance, creators cost 1 credit per this many (currently 4).
`usage.usage_pricing`	boolean	Whether usage-based pricing is on (Settings → MCP & API). Off = calls stop at the free allowance.
`usage.creators_returned`	number	Creators this call returned.
`usage.creators_charged`	number	Of those, how many were paid (past the free allowance).
`usage.credits_charged`	number	Credits this call charged.
`suggested_next`	string	Plain-English hint written for AI agents calling the API: what to do next. Safe to ignore in code.

Status values

`(absent)`	Success. The body is the search result.
`rate_limited`	429. Too many searches (20/minute) or the daily API search cap. See retry_after.
`usage_pricing_required`	402. Today's free creators are used up and usage-based pricing is off. Turn it on at settings_url or wait for 00:00 UTC.
`insufficient_credits`	402. Usage-based pricing is on but the credit balance is empty. Top up at topup_url.

Example response

{
  "total": 4812,
  "preview_creators": [
    {
      "name": "Example Skin Studio",
      "handle": "example.skinstudio",
      "platform": "instagram",
      "follower_count": 48210,
      "engagement_rate_pct": 3.8,
      "bio": "Licensed esthetician · acne-safe routines · LA",
      "location": "Los Angeles, United States",
      "is_verified": false,
      "profile_url": "https://www.instagram.com/example.skinstudio",
      "photo_url": "https://cdn.example.com/avatar.jpg"
    }
  ],
  "filters_used": {
    "basic": {
      "platform": "instagram",
      "contactDetails": [
        "EMAIL"
      ],
      "sortBy": "ENGAGEMENT_RATE"
    },
    "creator": {
      "audienceRange": {
        "minValue": 10000,
        "maxValue": 100000
      },
      "location": {
        "name": "United States"
      }
    },
    "content": {
      "bioKeywords": {
        "any": [
          "skincare",
          "esthetician"
        ],
        "all": [],
        "none": []
      }
    },
    "performance": {
      "engagementRate": {
        "minValue": 2
      }
    },
    "audience": {}
  },
  "filters_summary": "instagram · 10K–100K followers · United States · keywords: skincare, esthetician · 2%+ engagement · must have email · sorted by engagement rate",
  "offset": 0,
  "next_offset": 10,
  "page_request_id": "4a0e6c9e-2f7d-4c1a-9b8e-0d3f5e6a7b8c",
  "credits_remaining": 1250,
  "estimated_cost_per_creator": 1,
  "max_affordable_count": 1250,
  "source": "mcp",
  "usage": {
    "free_creators_per_day": 75,
    "free_creators_left": 65,
    "creators_per_credit": 4,
    "usage_pricing": false,
    "creators_returned": 10,
    "creators_charged": 0,
    "credits_charged": 0
  },
  "suggested_next": "You found 4812 matches. …"
}

Try it

Request body (JSON)This is a live request on your account and can spend credits. Free for the first 75 creators returned per UTC day (API and MCP together). After that, 1 credit per 4 creators returned if usage-based pricing is on, otherwise 402 until 00:00 UTC.

curl -X POST https://creatorlookup.com/api/v1/search_creators \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"basic":{"platform":"instagram","contactDetails":["EMAIL"],"sortBy":"ENGAGEMENT_RATE"},"creator":{"audienceRange":{"minValue":10000,"maxValue":100000},"location":{"name":"United States"}},"content":{"bioKeywords":{"any":["skincare","esthetician"],"all":[],"none":[]}},"performance":{"engagementRate":{"minValue":2}}}'

Analyze a creator (lookalike seed)

POST/api/v1/analyze_creator_content

Give one creator; get back their recent captions, bio (when tracked), follower count, the hashtags and terms they use most, and suggested_filters: a partial filter object (platform, a follower band around their size, top hashtags) you can merge into a search_creators request to find similar creators.

Untracked creators are fetched live, which can take 10-30 seconds.

Cost: Free. A live fetch counts toward the live-refresh rate limit.

Request body

Field	Type	Description
`platform`required	string	one of: instagram, tiktok, youtube
`handle`required	string	Username of the seed creator (a leading @ is fine).min length 2max length 64

Response

Field	Type	Description
`status`	"ok"
`handle`	string
`platform`	string	one of: instagram, tiktok, youtube
`profile`	object \| null	Stored profile, when we track the creator.
`profile.full_name`	string \| null
`profile.bio`	string \| null
`profile.followers`	number \| null
`profile.location`	string \| null
`posts`	object[]
`posts[].caption`	string \| null
`posts[].posted_at`	string \| null	ISO 8601 timestamp.
`posts[].post_type`	string \| null
`posts[].likes`	number \| null
`posts[].views`	number \| null
`hashtags`	object[]	Most used hashtags in the recent captions.
`hashtags[].tag`	string
`hashtags[].count`	number
`terms`	object[]	Salient words and phrases from bio and captions.
`terms[].term`	string
`terms[].count`	number
`follower_band`	object	Follower range around the creator's size. Absent when the size is unknown.
`follower_band.minValue`	number
`follower_band.maxValue`	number
`suggested_filters`	object (map)	Partial search_creators filters to start a lookalike search from.
`source`	string	Where the posts came from: db, live or profile-only.

Status values

`ok`	Success.
`unavailable`	No posts or bio could be found for this creator. `reason` explains.

Example response

{
  "status": "ok",
  "handle": "example.skinstudio",
  "platform": "instagram",
  "profile": {
    "full_name": "Example Skin Studio",
    "bio": "Licensed esthetician · acne-safe routines · LA",
    "followers": 48210,
    "location": "Los Angeles"
  },
  "posts": [
    {
      "caption": "3-step routine for oily skin #skincareroutine",
      "posted_at": "2026-10-09T17:02:00Z",
      "post_type": "reel",
      "likes": 2100,
      "views": 41000
    }
  ],
  "hashtags": [
    {
      "tag": "skincareroutine",
      "count": 4
    }
  ],
  "terms": [
    {
      "term": "esthetician",
      "count": 3
    },
    {
      "term": "acne",
      "count": 2
    }
  ],
  "follower_band": {
    "minValue": 20000,
    "maxValue": 100000
  },
  "suggested_filters": {
    "basic": {
      "platform": "instagram"
    },
    "creator": {
      "audienceRange": {
        "minValue": 20000,
        "maxValue": 100000
      }
    },
    "content": {
      "hashtags": [
        "skincareroutine"
      ]
    }
  },
  "source": "db"
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/analyze_creator_content \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"instagram","handle":"example.skinstudio"}'

Look up one creator

POST/api/v1/lookup_creator

Resolves a profile link (url) or platform + handle, unlocks the creator into your account's Database and returns a summary including their primary email when one is known. Share links (a YouTube video, a TikTok video) resolve to the creator.

Deep enrichment (every email, cross-platform stats) keeps running for about a minute after this returns. Call get_history_data with the returned history_id (and detail: "full") afterwards for the complete record.

Cost: 1 credit per creator you don't already own. Free if you already unlocked them.

Request body

Field	Type	Description
`url`	string	Profile link (instagram.com/…, tiktok.com/@…, youtube.com/@…). Pass it as the user gave it: anything after the handle (/reels, /video/…, ?hl=en) is ignored, and a YouTube video/Short or TikTok share link resolves to its creator.max length 500
`platform`	string	one of: instagram, tiktok, youtube
`handle`	string	Username without the @ — the exact handle, never a display name.max length 80

Response

Field	Type	Description
`status`	"complete"
`creator_id`	string	Creator Lookup's id for this creator.
`platform`	string	one of: instagram, tiktok, youtube
`handle`	string
`creator`	object	What is already known at return time; enrichment may add more within a minute.
`creator.full_name`	string \| null
`creator.primary_email`	string \| null
`creator.total_audience`	number \| null	Followers across platforms.
`creator.country`	string \| null
`charged`	boolean	Whether a credit was charged.
`already_owned`	boolean	You had already unlocked this creator.
`enrichment_running`	boolean
`history_id`	string \| null	Pass to get_history_data or add_to_list.
`history_url`	string
`note`	string

Status values

`complete`	Success.
`insufficient_credits`	402. 1 credit is needed and the balance is empty.
`rate_limited`	429. Too many live lookups. See retry_after_seconds. Nothing was charged.
`error`	422. The input is not a profile, or the creator could not be loaded (private, missing, wrong platform). `message` explains.

Example response

{
  "status": "complete",
  "creator_id": "9b2f8c1e-5d4a-4e3b-8a7f-1c2d3e4f5a6b",
  "platform": "instagram",
  "handle": "example.skinstudio",
  "creator": {
    "full_name": "Example Skin Studio",
    "primary_email": "hello@example.com",
    "total_audience": 48210,
    "country": "United States"
  },
  "charged": true,
  "already_owned": false,
  "enrichment_running": true,
  "history_id": "0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b",
  "history_url": "https://creatorlookup.com/industry/creators/history/0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b",
  "note": "Deep enrichment keeps filling this profile in for about a minute."
}

Try it

Request body (JSON)This is a live request on your account and can spend credits. 1 credit per creator you don't already own. Free if you already unlocked them.

curl -X POST https://creatorlookup.com/api/v1/lookup_creator \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.instagram.com/example.skinstudio/"}'

Unlock selected creators

POST/api/v1/unlock_creators

Unlock a specific set of creators by handle, for example the ones you picked from search_creators results. Returns at once with a history_id; unlocks run in the background (about 10 seconds per creator). Poll get_history_data with that id every 15-30 seconds until the creators appear.

Handles must be exact usernames (from search results), not display names. Optionally pass list_name to also save them to a list (created if missing).

confirmed must be true. It is a safety latch for AI agents; your code should always send it.

Cost: 1 credit per creator you don't already own. Owned creators are free.

Request body

Field	Type	Description
`platform`required	string	one of: instagram, tiktok, youtube
`handles`required	string[]	Usernames without the @, copied EXACTLY from search_creators/get_history_data results. Never guess a handle or derive one from a display name; a wrong handle silently fails to unlock. 1 credit each (free if already owned).at least 1 itemup to 25 items
`name`	string	Label for the history entry, e.g. 'Hand-picked tech fits'.max length 100
`list_name`	string	Also save the unlocked creators into this list (created if it doesn't exist).max length 80
`confirmed`	boolean	MUST be true, and may only be set true when the user explicitly asked for these unlocks — either they named the creators, or they told you to pick and unlock ('unlock the ones you think fit'). If YOU are proposing picks the user hasn't approved, call with confirmed:false (or present the picks and ask first).default: false

Response

Field	Type	Description
`status`	"processing"
`history_id`	string	Poll get_history_data with this id.
`history_url`	string
`requested`	number	Distinct handles queued.
`list`	object \| null	The list the creators are being added to, if list_name was given.
`list.id`	string	List id (UUID).
`list.name`	string
`estimated_seconds`	number
`note`	string

Status values

`processing`	Accepted. Poll get_history_data(history_id).
`needs_confirmation`	400. `confirmed` was not true. Nothing ran.
`error`	422. The batch could not start. `message` explains.

Example response

{
  "status": "processing",
  "history_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "history_url": "https://creatorlookup.com/industry/creators/history/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "requested": 2,
  "list": {
    "id": "7c6b5a49-3827-4165-9a8b-7c6d5e4f3a2b",
    "name": "Skincare Q4"
  },
  "estimated_seconds": 30,
  "note": "Unlocks are running in the background. …"
}

Try it

Request body (JSON)This is a live request on your account and can spend credits. 1 credit per creator you don't already own. Owned creators are free.

curl -X POST https://creatorlookup.com/api/v1/unlock_creators \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"instagram","handles":["example.skinstudio","example.glowlab"],"list_name":"Skincare Q4","confirmed":true}'

Get a creator's recent posts

POST/api/v1/get_creator_posts

Recent posts for one creator: link, caption, date, likes, views, comments, thumbnail, plus averages over the sample. Served from our database when we track the creator (fast); otherwise fetched live (10-30 seconds).

Cost: Free. A live fetch counts toward the live-refresh rate limit (60/hour, 300/day on paid plans).

Request body

Field	Type	Description
`platform`required	string	one of: instagram, tiktok, youtube
`handle`required	string	Username without the @.min length 2max length 64

Response

Field	Type	Description
`status`	"ok"
`handle`	string
`platform`	string	one of: instagram, tiktok, youtube
`source`	string	db = stored posts, live = fetched just now.one of: db, live
`metrics`	object \| null	Averages over the posts sampled (null with fewer than 3 posts).
`metrics.avg_likes`	number \| null
`metrics.avg_views`	number \| null
`metrics.avg_comments`	number \| null
`metrics.sampled`	number
`posts`	object[]
`posts[].url`	string \| null
`posts[].caption`	string \| null
`posts[].posted_at`	string \| null	ISO 8601 timestamp.
`posts[].likes`	number \| null
`posts[].views`	number \| null
`posts[].comments`	number \| null
`posts[].post_type`	string \| null
`posts[].thumbnail`	string \| null	Platform CDN links expire; do not store long-term.

Status values

`ok`	Success.
`unavailable`	Posts could not be fetched right now.

Example response

{
  "status": "ok",
  "handle": "example.creator",
  "platform": "tiktok",
  "source": "db",
  "metrics": {
    "avg_likes": 5400,
    "avg_views": 88000,
    "avg_comments": 130,
    "sampled": 6
  },
  "posts": [
    {
      "url": "https://www.tiktok.com/@example.creator/video/1",
      "caption": "Morning routine",
      "posted_at": "2026-10-10T14:00:00Z",
      "likes": 6100,
      "views": 91000,
      "comments": 140,
      "post_type": "video",
      "thumbnail": "https://cdn.example.com/t.jpg"
    }
  ]
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/get_creator_posts \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"tiktok","handle":"example.creator"}'

Export a search

POST/api/v1/run_export

Re-runs a search and exports its top limit creators (same sort order) with their contact details into your account. Pass the filters_used object from a search_creators response as filters.

Exports run in the background: the response is usually processing with an export_id. Poll get_history_data with history_id = export_id every 30-60 seconds until status is complete, then page through the rows (up to 500 per call). Most exports finish in 1-3 minutes.

The balance must cover limit credits up front. confirmed must be true (a safety latch for AI agents).

Cost: Up to 1 credit per creator exported; creators you already own are free.

Request body

Field	Type	Description
`filters`required	object	The same filters used in the most recent search_creators call. Pass them verbatim — the export re-runs the search and pulls the top N creators by the same sort order.
`filters.basic`required in parent	object	Required. Platform, contact requirement and sort order.
`filters.basic.platform`required in parent	string	Which network to search. One platform per search.one of: instagram, youtube, tiktok
`filters.basic.contactDetails`	string[]	Only return creators who list ALL of these contact channels. Defaults to ["EMAIL"] when omitted; pass [] to include creators without a public email (a much larger pool). 26 allowed values `EMAILPHONELINKTREEBBMKIKSKYPEWHATSAPPWECHATTELEGRAMVIBERINSTAGRAMYOUTUBETIKTOKTWITTERSNAPCHATFACEBOOKWEIBOITUNESKAKAOPINTERESTLINEIDTWITCHTVSARAHAHSAYATTUMBLRVK`
`filters.basic.sortBy`	string	Result order (descending). Defaults to FOLLOWER_COUNT. Common: FOLLOWER_COUNT, ENGAGEMENT_RATE, AVERAGE_VIEWS, AVERAGE_LIKES, FOLLOWER_GROWTH. Some values only apply to some platforms. 24 allowed values `DESCRIPTIONAVERAGE_LIKEAVERAGE_LIKESAUDIENCE_LOCATIONAUDIENCE_LOCATIONSAUDIENCE_LANGUAGEAUDIENCE_AGEAUDIENCE_INTERESTSAUDIENCE_LOOKALIKESAUDIENCE_BRAND_AFFINITIESFOLLOWER_COUNTFOLLOWER_GROWTHAIRTIMEENGAGEMENT_RATETOPIC_RELEVANCEAVERAGE_VIEWSREELS_VIEWSPEAK_VIEWERSAVG_CONCURRENT_VIEWERSTOTAL_VIEWS_GROWTHTOTAL_LIKES_GROWTHHOURS_WATCHEDCREATOR_LOOKALIKESCONTENT_COUNT`
`filters.creator`	object	Filters on the creator themself: size, location, language, demographics.
`filters.creator.audienceRange`	object	Follower (subscriber) count range, e.g. {minValue: 10000, maxValue: 100000} for micro creators.
`filters.creator.audienceRange.minValue`	number	Inclusive lower bound. Omit for no minimum.
`filters.creator.audienceRange.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`filters.creator.location`	object	Where the CREATOR is based.send one of: {id, display_name?} or {name}
`filters.creator.location.id`	string	Location id from search_locations.form A, required in that form
`filters.creator.location.display_name`	string	form A
`filters.creator.location.name`	string	Plain place name, e.g. "United States", "California", "London". Resolved to the best match.form B, required in that form
`filters.creator.language`	object	The language the creator posts in.send one of: {code, name?} or {name}
`filters.creator.language.code`	string	ISO 639-1 language code from search_languages, e.g. "en".form A, required in that form
`filters.creator.language.name`	string	form A
`filters.creator.language.name`	string	Language name, e.g. "Spanish". Resolved to its code.form B, required in that form
`filters.creator.gender`	object	The creator's gender.
`filters.creator.gender.code`required in parent	string	one of: MALE, FEMALE
`filters.creator.age`	object	The creator's age in years.
`filters.creator.age.minValue`	number	Inclusive lower bound. Omit for no minimum.
`filters.creator.age.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`filters.creator.verified`	object	{value: true} for verified (blue check) accounts only.
`filters.creator.verified.value`required in parent	boolean
`filters.creator.interests`	object	Instagram only. Interest names from search_interests, e.g. ["Fitness & Yoga"]. Ignored on other platforms.
`filters.creator.interests.values`required in parent	string[]
`filters.creator.accountType`	object	Instagram only. Any of PERSONAL, BUSINESS, CREATOR. Ignored on other platforms.
`filters.creator.accountType.types`required in parent	string[]
`filters.creator.lookalikeCreators`	string	Platform lookalike filter: a seed creator's username without the @.
`filters.audience`	object	Filters on the creator's followers (audience demographics).
`filters.audience.location`	object	Where the creator's AUDIENCE (followers) is located.
`filters.audience.location.id`	string	Location id from search_locations.
`filters.audience.location.name`	string	Plain place name, e.g. "Germany". Give id or name.
`filters.audience.location.percentage`	number	At least this percent (0-100) of the creator's audience must match.min 0max 100
`filters.audience.age`	object	The audience's age band.
`filters.audience.age.minValue`	number	Youngest age in the band, in years.
`filters.audience.age.maxValue`	number	Oldest age in the band, in years.
`filters.audience.age.percentage`	number	At least this percent (0-100) of the audience is in the band.min 0max 100
`filters.audience.gender`	object	The audience's gender split.
`filters.audience.gender.code`required in parent	string	one of: MALE, FEMALE
`filters.audience.gender.percentage`	number	At least this percent (0-100) of the creator's audience must match.min 0max 100
`filters.audience.language`	object	The language the audience speaks.
`filters.audience.language.code`	string	ISO 639-1 code from search_languages.
`filters.audience.language.name`	string	Language name. Give code or name.
`filters.audience.language.percentage`	number	At least this percent (0-100) of the creator's audience must match.min 0max 100
`filters.audience.audienceLookalike`	string	Username (no @) of a creator whose audience the results' audiences should resemble.
`filters.audience.audienceCredibilityScore`	number	Minimum share of real (non-bot) followers, 0-1. E.g. 0.8 = at least 80% credible followers.min 0max 1
`filters.content`	object	Filters on what the creator writes and posts: bio, captions, hashtags, topics, recency.
`filters.content.bioKeywords`	object	Keywords matched against the profile bio. A multi-word entry matches bios containing all of its words, in any order. Example: {any: ["skincare", "esthetician"], none: ["agency"]}.
`filters.content.bioKeywords.any`	string[]	Bio contains at least one of these. The best niche filter on Instagram/TikTok.
`filters.content.bioKeywords.all`	string[]	Bio must also contain every one of these.
`filters.content.bioKeywords.none`	string[]	Bio contains none of these.
`filters.content.captionKeywords`	object	Words used in recent post captions. Narrows the pool sharply on Instagram/TikTok; add it after bio keywords if needed.
`filters.content.captionKeywords.keywords`required in parent	string[]
`filters.content.hashtags`	string[]	Instagram and TikTok only. Hashtags without the #, e.g. ["skincareroutine"].
`filters.content.mostRecentPosts`	string \| null	Only creators who posted on or after this date (YYYY-MM-DD). Use to exclude inactive accounts.
`filters.content.topics`	string[]	Content topics from search_topics, e.g. ["gaming"]. Works best on YouTube.
`filters.content.minPostCount`	integer	Minimum number of posts on the account.min 0max 9007199254740991
`filters.content.maxPostCount`	integer	Maximum number of posts on the account.min 0max 9007199254740991
`filters.performance`	object	Filters on engagement and growth.
`filters.performance.averageLikes`	object	Average likes per post.
`filters.performance.averageLikes.minValue`	number	Inclusive lower bound. Omit for no minimum.
`filters.performance.averageLikes.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`filters.performance.averageViews`	object	Average views per video/reel.
`filters.performance.averageViews.minValue`	number	Inclusive lower bound. Omit for no minimum.
`filters.performance.averageViews.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`filters.performance.engagementRate`	object	Engagement rate in PERCENT, e.g. {minValue: 3} = at least 3%. (Search results report it as engagement_rate_pct, same unit.)
`filters.performance.engagementRate.minValue`	number	Inclusive lower bound. Omit for no minimum.
`filters.performance.engagementRate.maxValue`	number	Inclusive upper bound. Omit for no maximum.
`filters.performance.audienceGrowth`	object	Fast-growing creators: grew at least `percentage`% in the last `interval` months.
`filters.performance.audienceGrowth.interval`	number	Lookback window in months, 1-6.
`filters.performance.audienceGrowth.percentage`	number	Minimum follower growth in percent over that window.
`limit`required	integer	How many creators to export. REQUIRED — ASK the user how many they want before calling. Never silently export the full match count.min 1max 10000
`format`	string	one of: basic, fulldefault: "basic"
`confirmed`	boolean	MUST be true, and may only be set true after the user explicitly confirmed this exact limit in the conversation. Calling with confirmed:false is rejected.default: false

Response

Field	Type	Description
`status`	string	one of: processing, complete
`export_id`	string	Pass as history_id to get_history_data.
`history_url`	string
`estimated_seconds`	number	processing only.
`credits_to_charge`	number	processing only: the most this export can charge.
`credits_used`	number	complete only.
`credits_remaining`	number	complete only.
`creators`	any[]	complete only: always empty; read rows with get_history_data.

Status values

`processing`	Accepted. Poll get_history_data(export_id).
`complete`	Finished at once (small exports). Read rows with get_history_data(export_id).
`insufficient_credits`	402. The balance does not cover `limit` credits.
`needs_confirmation`	400. `confirmed` was not true. Nothing ran.

Example response

{
  "status": "processing",
  "export_id": "5e4d3c2b-1a09-4f8e-9d7c-6b5a4f3e2d1c",
  "history_url": "https://creatorlookup.com/industry/creators/history/5e4d3c2b-1a09-4f8e-9d7c-6b5a4f3e2d1c",
  "estimated_seconds": 60,
  "credits_to_charge": 100
}

Try it

Request body (JSON)This is a live request on your account and can spend credits. Up to 1 credit per creator exported; creators you already own are free.

curl -X POST https://creatorlookup.com/api/v1/run_export \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"basic":{"platform":"instagram","contactDetails":["EMAIL"],"sortBy":"ENGAGEMENT_RATE"},"creator":{"audienceRange":{"minValue":10000,"maxValue":100000},"location":{"name":"United States"}},"content":{"bioKeywords":{"any":["skincare","esthetician"],"all":[],"none":[]}},"performance":{"engagementRate":{"minValue":2}},"audience":{}},"limit":100,"format":"basic","confirmed":true}'

Get export / unlock results

POST/api/v1/get_history_data

Returns the creators saved by an export, unlock or lookup, with contact details, in pages of up to 500. While the job is still running it returns status: "processing"; poll every 30-60 seconds.

detail: "preview" gives name, handle, platform, followers, primary email and location. detail: "full" adds every email found and the full stored profile (raw_metadata). Paginate with offset until has_more is false.

Cost: Free. These creators are already unlocked.

Request body

Field	Type	Description
`history_id`required	string
`detail`	string	preview: name, handle, platform, follower_count, email, country, profile_url. full: same plus all_emails and the raw metadata blob.one of: preview, fulldefault: "preview"
`limit`	integer	How many creators to return in this call. Paginate with offset for the rest.default: 100min 1max 500
`offset`	integer	Skip this many results before returning. Use for pagination across an export's full set (e.g. offset=100, limit=100 returns rows 101–200).default: 0min 0max 9007199254740991

Response

Field	Type	Description
`status`	string	one of: complete, processing
`history_url`	string
`creators`	object[]	complete only.
`creators[].rank`	number \| null	Position in the search order (1 = first).
`creators[].name`	string \| null
`creators[].handle`	string \| null	Username on `platform`.
`creators[].platform`	string \| null
`creators[].follower_count`	number
`creators[].email`	string \| null	Primary business email, when one was found.
`creators[].country`	string \| null
`creators[].state`	string \| null
`creators[].city`	string \| null
`creators[].primary_niche`	string \| null
`creators[].profile_url`	string \| null
`creators[].all_emails`	string[]	detail=full only: every email found for the creator.
`creators[].raw_metadata`	any	detail=full only: the full stored profile (cross-platform usernames, links, stats). Shape may grow over time.
`total_count`	number	complete only: creators in the whole job.
`returned`	number	complete only: creators in this page.
`offset`	number
`has_more`	boolean	complete only: call again with offset + returned.
`filters_used`	any	complete only: the search that produced this job, when there was one.
`estimated_seconds_remaining`	number	processing only.

Status values

`complete`	Rows are ready.
`processing`	The job is still running. Poll again in 30-60 seconds.

Example response

{
  "status": "complete",
  "history_url": "https://creatorlookup.com/industry/creators/history/5e4d3c2b-1a09-4f8e-9d7c-6b5a4f3e2d1c",
  "creators": [
    {
      "rank": 1,
      "name": "Example Skin Studio",
      "handle": "example.skinstudio",
      "platform": "instagram",
      "follower_count": 48210,
      "email": "hello@example.com",
      "country": "United States",
      "state": "California",
      "city": "Los Angeles",
      "primary_niche": "Beauty",
      "profile_url": "https://www.instagram.com/example.skinstudio"
    }
  ],
  "total_count": 100,
  "returned": 1,
  "offset": 0,
  "has_more": true,
  "filters_used": null
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/get_history_data \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"history_id":"5e4d3c2b-1a09-4f8e-9d7c-6b5a4f3e2d1c","detail":"preview","limit":100,"offset":0}'

List search history

POST/api/v1/list_search_history

The same history the app shows under Creators → History. Use an item's id as history_id for get_history_data or add_to_list.

Cost: Free.

Request body

Field	Type	Description
`limit`	integer	default: 10min 1max 50
`offset`	integer	default: 0min 0max 9007199254740991
`kind`	string	one of: all, searches, exportsdefault: "all"

Response

Field	Type	Description
`items`	object[]
`items[].id`	string	history_id.
`items[].kind`	string	one of: search, export
`items[].filters_summary`	string
`items[].total`	number	Creators in the result.
`items[].status`	string	SUCCESS, PROCESSING, FAILED, …
`items[].created_at`	string	ISO 8601.
`items[].source`	string	Where it was made: web, ai_mode, mcp.
`items[].name`	string \| null
`total_count`	number	Items matching `kind` (for pagination).

Status values

(absent) Success.

Example response

{
  "items": [
    {
      "id": "5e4d3c2b-1a09-4f8e-9d7c-6b5a4f3e2d1c",
      "kind": "export",
      "filters_summary": "instagram, 10000–100000 followers, bio match",
      "total": 100,
      "status": "SUCCESS",
      "created_at": "2026-10-13T15:02:11Z",
      "source": "mcp",
      "name": null
    }
  ],
  "total_count": 1
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/list_search_history \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"exports","limit":10,"offset":0}'

Get lists

POST/api/v1/get_lists

All of the account's creator lists. Lists are also visible in the app under Creators → Lists.

Cost: Free.

Request body

No fields. Send an empty object: {}

Response

Field	Type	Description
`lists`	object[]
`lists[].id`	string	List id (UUID).
`lists[].name`	string
`lists[].url`	string	The list in the Creator Lookup app.
`lists[].creator_count`	number \| null
`note`	string

Status values

(absent) Success.

Example response

{
  "lists": [
    {
      "id": "7c6b5a49-3827-4165-9a8b-7c6d5e4f3a2b",
      "name": "Skincare Q4",
      "creator_count": 42,
      "url": "https://creatorlookup.com/industry/creators/lists/7c6b5a49-3827-4165-9a8b-7c6d5e4f3a2b"
    }
  ],
  "note": "Lists live at /industry/creators/lists in the app."
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/get_lists \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Create a list

POST/api/v1/create_list

Creates a list by name. If a list with that name (case-insensitive) exists, it is returned instead.

Cost: Free.

Request body

Field	Type	Description
`name`required	string	List name, e.g. 'Cold brew UGC shortlist'.max length 80

Response

Field	Type	Description
`status`	"ok"
`list`	object
`list.id`	string	List id (UUID).
`list.name`	string
`list.url`	string	The list in the Creator Lookup app.
`list.creator_count`	number \| null

Status values

`ok`	Success.
`error`	422. The list could not be created.

Example response

{
  "status": "ok",
  "list": {
    "id": "7c6b5a49-3827-4165-9a8b-7c6d5e4f3a2b",
    "name": "Skincare Q4",
    "creator_count": 0,
    "url": "https://creatorlookup.com/industry/creators/lists/7c6b5a49-3827-4165-9a8b-7c6d5e4f3a2b"
  }
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/create_list \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Skincare Q4"}'

Add creators to a list

POST/api/v1/add_to_list

Adds all creators from one history entry (history_id from run_export, unlock_creators, lookup_creator or list_search_history) to a list, by list name or id. The list is created if it doesn't exist. Wait until the job is complete first.

Cost: Free. The creators are already unlocked.

Request body

Field	Type	Description
`list`required	string	Target list, by name or id. Created automatically if it doesn't exist.max length 80
`history_id`required	string	A discovery event id (from run_export, unlock_creators, lookup_creator, or list_search_history) — ALL creators in that event are added to the list. Owned creators only.format: uuid

Response

Field	Type	Description
`status`	"ok"
`list`	object
`list.id`	string	List id (UUID).
`list.name`	string
`list.url`	string	The list in the Creator Lookup app.
`added`	number	Creators added.

Status values

`ok`	Success.
`empty`	The history entry has no creators yet (still processing?).
`error`	422. `message` explains.

Example response

{
  "status": "ok",
  "list": {
    "id": "7c6b5a49-3827-4165-9a8b-7c6d5e4f3a2b",
    "name": "Skincare Q4",
    "url": "https://creatorlookup.com/industry/creators/lists/7c6b5a49-3827-4165-9a8b-7c6d5e4f3a2b"
  },
  "added": 100
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/add_to_list \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list":"Skincare Q4","history_id":"5e4d3c2b-1a09-4f8e-9d7c-6b5a4f3e2d1c"}'

Get list creators

POST/api/v1/get_list_creators

Pages through one list (by name or id), 100 creators per call at most.

Cost: Free.

Request body

Field	Type	Description
`list`required	string	List name or id.max length 80
`limit`	integer	default: 20min 1max 100
`offset`	integer	default: 0min 0max 9007199254740991

Response

Field	Type	Description
`status`	"ok"
`list`	object
`list.id`	string	List id (UUID).
`list.name`	string
`list.url`	string	The list in the Creator Lookup app.
`creators`	object[]
`creators[].id`	string
`creators[].full_name`	string \| null
`creators[].primary_email`	string \| null
`creators[].phone`	string \| null
`creators[].gender`	string \| null
`creators[].country`	string \| null
`creators[].state`	string \| null
`creators[].city`	string \| null
`creators[].language`	string \| null
`creators[].total_audience`	number \| null	Followers across platforms.
`creators[].total_reach`	number \| null
`creators[].avatar_url`	string \| null
`creators[].platforms`	string[] \| null
`creators[].metadata`	any	Full stored profile (usernames, links, stats per platform).
`creators[].created_at`	string
`creators[].updated_at`	string

Status values

`ok`	Success.
`not_found`	404. No list with that name or id.

Example response

{
  "status": "ok",
  "list": {
    "id": "7c6b5a49-3827-4165-9a8b-7c6d5e4f3a2b",
    "name": "Skincare Q4",
    "url": "https://creatorlookup.com/industry/creators/lists/7c6b5a49-3827-4165-9a8b-7c6d5e4f3a2b"
  },
  "creators": [
    {
      "id": "9b2f8c1e-5d4a-4e3b-8a7f-1c2d3e4f5a6b",
      "full_name": "Example Skin Studio",
      "primary_email": "hello@example.com",
      "phone": null,
      "gender": "FEMALE",
      "country": "United States",
      "state": "California",
      "city": "Los Angeles",
      "language": "en",
      "total_audience": 48210,
      "total_reach": 48210,
      "avatar_url": null,
      "platforms": [
        "instagram"
      ],
      "metadata": {
        "all_usernames": {
          "instagram": "example.skinstudio"
        }
      },
      "created_at": "2026-10-01T10:00:00Z",
      "updated_at": "2026-10-12T10:00:00Z"
    }
  ]
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/get_list_creators \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list":"Skincare Q4","limit":20,"offset":0}'

Search locations

POST/api/v1/search_locations

Autocomplete for creator.location and audience.location. Plain names also work in filters; use this when you need an exact id.

Cost: Free.

Request body

Field	Type	Description
`query`required	string
`limit`	integer	default: 12min 1max 30

Response

Field	Type	Description
`items`	object[]
`items[].id`	string
`items[].display_name`	string
`items[].type`	string	COUNTRY, STATE, CITY, …

Status values

(absent) Success.

Example response

{
  "items": [
    {
      "id": "c3f1e0a2-0000-0000-0000-000000000000",
      "display_name": "Texas, United States",
      "type": "STATE"
    }
  ]
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/search_locations \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"texas","limit":3}'

Search languages

POST/api/v1/search_languages

Autocomplete for creator.language and audience.language.

Cost: Free.

Request body

Field	Type	Description
`query`	string	default: ""
`limit`	integer	default: 12min 1max 30

Response

Field	Type	Description
`items`	object[]
`items[].code`	string
`items[].name`	string

Status values

(absent) Success.

Example response

{
  "items": [
    {
      "code": "es",
      "name": "Spanish"
    }
  ]
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/search_languages \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"span","limit":3}'

Search interests

POST/api/v1/search_interests

Values for creator.interests.values (Instagram only).

Cost: Free.

Request body

Field	Type	Description
`query`	string	default: ""
`limit`	integer	default: 12min 1max 30

Response

Field	Type	Description
`items`	object[]
`items[].name`	string

Status values

(absent) Success.

Example response

{
  "items": [
    {
      "name": "Fitness & Yoga"
    }
  ]
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/search_interests \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"fit","limit":3}'

Search topics

POST/api/v1/search_topics

Values for content.topics.

Cost: Free.

Request body

Field	Type	Description
`query`	string	default: ""
`platform`	string	one of: instagram, youtube, tiktok
`limit`	integer	default: 12min 1max 30

Response

Field	Type	Description
`items`	object[]
`items[].name`	string
`items[].value`	string
`error`	string

Status values

(absent) Success. On a lookup failure `items` is empty and `error` is set.

Example response

{
  "items": [
    {
      "name": "gaming",
      "value": "gaming"
    }
  ]
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/search_topics \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"gaming","platform":"youtube","limit":3}'

Search handles

POST/api/v1/search_handles

Useful for creator.lookalikeCreators, audience.audienceLookalike, or to check an exact handle before lookup_creator.

Cost: Free.

Request body

Field	Type	Description
`query`required	string
`platform`	string	one of: instagram, youtube, tiktok
`limit`	integer	default: 8min 1max 20

Response

Field	Type	Description
`items`	object[]
`items[].handle`	string
`items[].full_name`	string
`items[].followers`	number
`error`	string

Status values

(absent) Success. On a lookup failure `items` is empty and `error` is set.

Example response

{
  "items": [
    {
      "handle": "example.skinstudio",
      "full_name": "Example Skin Studio",
      "followers": 48210
    }
  ]
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/search_handles \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"example","platform":"instagram","limit":3}'

Get credit balance

POST/api/v1/get_credit_balance

The account's credit balance and its API/MCP billing settings. A good first call to check your key works.

Cost: Free.

Request body

No fields. Send an empty object: {}

Response

Field	Type	Description
`balance`	number	Credits available.
`plan`	string
`trial`	boolean
`mcp_api`	object
`mcp_api.free_creators_per_day`	number
`mcp_api.creators_per_credit`	number
`mcp_api.usage_pricing`	boolean \| null	Usage-based pricing on/off (null if it could not be read).
`mcp_api.settings_url`	string
`mcp_api.note`	string

Status values

(absent) Success.

Example response

{
  "balance": 1250,
  "plan": "Paid",
  "trial": false,
  "mcp_api": {
    "free_creators_per_day": 75,
    "creators_per_credit": 4,
    "usage_pricing": false,
    "settings_url": "https://creatorlookup.com/login?redirect=%2Findustry%2Fsettings%2Fmcp",
    "note": "Usage-based pricing is off: …"
  }
}

Try it

Request body (JSON)

curl -X POST https://creatorlookup.com/api/v1/get_credit_balance \
  -H "Authorization: Bearer $CREATORLOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'