{ "openapi": "3.1.0", "info": { "title": "Creator Lookup API", "version": "1.0.0", "description": "## Overview\n\nThe 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.\n\n- Base URL: `https://creatorlookup.com/api/v1`\n- Every endpoint is `POST https://creatorlookup.com/api/v1/{endpoint}` with a JSON body and a JSON response.\n- 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.\n- Machine-readable spec: [openapi.json](https://creatorlookup.com/api/v1/openapi.json). Whole reference as one Markdown file for AI assistants: [/docs/api.md](https://creatorlookup.com/docs/api.md).\n\n## Authentication\n\nFind your API key in the app under **Settings → MCP & API** ([open](https://creatorlookup.com/industry/settings/mcp)). Send it on every request:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n`X-API-Key: YOUR_API_KEY` works too.\n\n- API access needs an active paid plan (AppSumo plans included) or a positive credit balance. Otherwise requests get `403 api_access_requires_plan`.\n- 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.\n- Need a new key? Contact support and we will rotate it; the old one stops working at once.\n\n## Quickstart\n\n1. Check your key and balance:\n\n```bash\ncurl -X POST https://creatorlookup.com/api/v1/get_credit_balance \\\n -H \"Authorization: Bearer $CREATORLOOKUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'\n```\n\n2. Search. Only `basic.platform` is required:\n\n```bash\ncurl -X POST https://creatorlookup.com/api/v1/search_creators \\\n -H \"Authorization: Bearer $CREATORLOOKUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"basic\":{\"platform\":\"instagram\"},\"creator\":{\"audienceRange\":{\"minValue\":10000,\"maxValue\":100000}},\"content\":{\"bioKeywords\":{\"any\":[\"skincare\"]}}}'\n```\n\n3. 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.\n\n4. Poll `get_history_data` with that id until `status` is `complete`, then page through the rows (emails included).\n\n## Credits and limits\n\nCredits are shared with your account in the app. Rate limits are per account, across the API, MCP and the app ([full limits](https://creatorlookup.com/docs/limits)).\n\n| What | Cost |\n| --- | --- |\n| 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. |\n| Unlock or look up a creator | 1 credit per creator you don't already own. Owned creators are free. |\n| Export (`run_export`) | Up to 1 credit per creator exported; already-owned creators are free. The balance must cover `limit` up front. |\n| Reading results, lists, history, posts, filter values, balance | Free |\n\n| Limit | Value |\n| --- | --- |\n| Searches | 20 per minute |\n| Live profile and post fetches | 60 per hour, 300 per day (paid) |\n| Exports | 5 per minute, 40 per hour, 200 per day |\n| Unlocks | 30 per minute, 1,500 per day |\n| Creators per search page | 10 (page with `offset`, up to 500 per search) |\n| Creators per `get_history_data` call | 500 |\n| Creators per export | 10,000 |\n| Handles per `unlock_creators` call | 25 |\n\nHitting 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.\n\n## Responses and errors\n\nSuccessful responses are `200` with the endpoint's JSON. Many responses carry a `status` field; the HTTP status code follows it:\n\n| HTTP | `status` | Meaning |\n| --- | --- | --- |\n| 200 | ok, complete, processing, empty, unavailable, or none | Success. `processing` means a background job is still running. |\n| 400 | invalid_request | The body failed validation. `errors` lists each field and problem. |\n| 400 | needs_confirmation | `confirmed: true` was missing on a credit-spending call. Nothing ran. |\n| 401 | unauthorized | Missing or invalid API key. |\n| 402 | usage_pricing_required | Today's free API creators are used up and usage-based pricing is off. |\n| 402 | insufficient_credits | Not enough credits. `topup_url` / `purchase_url` says where to buy more. |\n| 403 | api_access_requires_plan, account_suspended | The account cannot use the API. |\n| 404 | not_found | Unknown endpoint, or the list/item does not exist. |\n| 422 | error | The request was valid but could not be done (for example a private profile). `message` explains. |\n| 429 | rate_limited | Too many requests. See `Retry-After` / `retry_after`. |\n| 500 | error | Our fault. Safe to retry reads; check history before retrying exports. |\n\nError 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.\n\n## Background jobs\n\n`run_export` and `unlock_creators` return immediately with an id (`export_id` / `history_id`) and keep working in the background. To get the results:\n\n1. Call `get_history_data` with `{\"history_id\": \"\"}` every 30-60 seconds.\n2. While it returns `status: \"processing\"`, wait and try again. Most jobs finish in 1-3 minutes.\n3. When `status` is `complete`, read `creators`. If `has_more` is true, call again with `offset` increased by `returned`.\n\nDon'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.\n\n## Data use and compliance\n\nCreator 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.\n\nData is provided as-is under our [Terms of Service](https://creatorlookup.com/terms). 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.\n\n## Building with AI assistants\n\nPoint Claude, ChatGPT or Cursor at [https://creatorlookup.com/docs/api.md](https://creatorlookup.com/docs/api.md) (the full reference in one file) or at the [OpenAPI spec](https://creatorlookup.com/api/v1/openapi.json) and ask it to write the integration.\n\nIf you want an assistant to use Creator Lookup directly instead of writing code, connect our MCP server: [MCP setup](https://creatorlookup.com/integrations/mcp).", "contact": { "name": "Creator Lookup", "email": "jose@creatorlookup.com", "url": "https://creatorlookup.com/docs/api" }, "termsOfService": "https://creatorlookup.com/terms" }, "servers": [ { "url": "https://creatorlookup.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Search" }, { "name": "Creators" }, { "name": "Exports & history" }, { "name": "Lists" }, { "name": "Filter values" }, { "name": "Account" } ], "paths": { "/search_creators": { "post": { "operationId": "search_creators", "summary": "Search creators", "description": "Find creators matching filters. Returns 10 at a time plus the total match count.\n\nThe 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.\n\nPage through the same search with `offset` (0, 10, 20, … up to 490). Each response gives the next offset in `next_offset`.\n\nSearches 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`.\n\nTips: 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`.\n\n**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.\n\n**status values:**\n- `(absent)`: Success. The body is the search result.\n- `rate_limited`: 429. Too many searches (20/minute) or the daily API search cap. See retry_after.\n- `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.\n- `insufficient_credits`: 402. Usage-based pricing is on but the credit balance is empty. Top up at topup_url.", "tags": [ "Search" ], "x-credit-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.", "x-spends-credits": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "basic": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "instagram", "youtube", "tiktok" ], "description": "Which network to search. One platform per search." }, "contactDetails": { "description": "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).", "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "PHONE", "LINKTREE", "BBM", "KIK", "SKYPE", "WHATSAPP", "WECHAT", "TELEGRAM", "VIBER", "INSTAGRAM", "YOUTUBE", "TIKTOK", "TWITTER", "SNAPCHAT", "FACEBOOK", "WEIBO", "ITUNES", "KAKAO", "PINTEREST", "LINEID", "TWITCHTV", "SARAHAH", "SAYAT", "TUMBLR", "VK" ] } }, "sortBy": { "description": "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.", "type": "string", "enum": [ "DESCRIPTION", "AVERAGE_LIKE", "AVERAGE_LIKES", "AUDIENCE_LOCATION", "AUDIENCE_LOCATIONS", "AUDIENCE_LANGUAGE", "AUDIENCE_AGE", "AUDIENCE_INTERESTS", "AUDIENCE_LOOKALIKES", "AUDIENCE_BRAND_AFFINITIES", "FOLLOWER_COUNT", "FOLLOWER_GROWTH", "AIRTIME", "ENGAGEMENT_RATE", "TOPIC_RELEVANCE", "AVERAGE_VIEWS", "REELS_VIEWS", "PEAK_VIEWERS", "AVG_CONCURRENT_VIEWERS", "TOTAL_VIEWS_GROWTH", "TOTAL_LIKES_GROWTH", "HOURS_WATCHED", "CREATOR_LOOKALIKES", "CONTENT_COUNT" ] } }, "required": [ "platform" ], "description": "Required. Platform, contact requirement and sort order." }, "creator": { "default": {}, "description": "Filters on the creator themself: size, location, language, demographics.", "type": "object", "properties": { "audienceRange": { "description": "Follower (subscriber) count range, e.g. {minValue: 10000, maxValue: 100000} for micro creators.", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "location": { "description": "Where the CREATOR is based.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Location id from search_locations." }, "display_name": { "type": "string" } }, "required": [ "id" ] }, { "type": "object", "properties": { "name": { "type": "string", "description": "Plain place name, e.g. \"United States\", \"California\", \"London\". Resolved to the best match." } }, "required": [ "name" ] } ] }, "language": { "description": "The language the creator posts in.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "ISO 639-1 language code from search_languages, e.g. \"en\"." }, "name": { "type": "string" } }, "required": [ "code" ] }, { "type": "object", "properties": { "name": { "type": "string", "description": "Language name, e.g. \"Spanish\". Resolved to its code." } }, "required": [ "name" ] } ] }, "gender": { "description": "The creator's gender.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "MALE", "FEMALE" ] } }, "required": [ "code" ] }, "age": { "description": "The creator's age in years.", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "verified": { "description": "{value: true} for verified (blue check) accounts only.", "type": "object", "properties": { "value": { "type": "boolean" } }, "required": [ "value" ] }, "interests": { "description": "Instagram only. Interest names from search_interests, e.g. [\"Fitness & Yoga\"]. Ignored on other platforms.", "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "values" ] }, "accountType": { "description": "Instagram only. Any of PERSONAL, BUSINESS, CREATOR. Ignored on other platforms.", "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" } } }, "required": [ "types" ] }, "lookalikeCreators": { "description": "Platform lookalike filter: a seed creator's username without the @.", "type": "string" } } }, "audience": { "default": {}, "description": "Filters on the creator's followers (audience demographics).", "type": "object", "properties": { "location": { "description": "Where the creator's AUDIENCE (followers) is located.", "type": "object", "properties": { "id": { "description": "Location id from search_locations.", "type": "string" }, "name": { "description": "Plain place name, e.g. \"Germany\". Give id or name.", "type": "string" }, "percentage": { "description": "At least this percent (0-100) of the creator's audience must match.", "type": "number", "minimum": 0, "maximum": 100 } } }, "age": { "description": "The audience's age band.", "type": "object", "properties": { "minValue": { "description": "Youngest age in the band, in years.", "type": "number" }, "maxValue": { "description": "Oldest age in the band, in years.", "type": "number" }, "percentage": { "description": "At least this percent (0-100) of the audience is in the band.", "type": "number", "minimum": 0, "maximum": 100 } } }, "gender": { "description": "The audience's gender split.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "MALE", "FEMALE" ] }, "percentage": { "description": "At least this percent (0-100) of the creator's audience must match.", "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "code" ] }, "language": { "description": "The language the audience speaks.", "type": "object", "properties": { "code": { "description": "ISO 639-1 code from search_languages.", "type": "string" }, "name": { "description": "Language name. Give code or name.", "type": "string" }, "percentage": { "description": "At least this percent (0-100) of the creator's audience must match.", "type": "number", "minimum": 0, "maximum": 100 } } }, "audienceLookalike": { "description": "Username (no @) of a creator whose audience the results' audiences should resemble.", "type": "string" }, "audienceCredibilityScore": { "description": "Minimum share of real (non-bot) followers, 0-1. E.g. 0.8 = at least 80% credible followers.", "type": "number", "minimum": 0, "maximum": 1 } } }, "content": { "default": {}, "description": "Filters on what the creator writes and posts: bio, captions, hashtags, topics, recency.", "type": "object", "properties": { "bioKeywords": { "type": "object", "properties": { "any": { "default": [], "description": "Bio contains at least one of these. The best niche filter on Instagram/TikTok.", "type": "array", "items": { "type": "string" } }, "all": { "default": [], "description": "Bio must also contain every one of these.", "type": "array", "items": { "type": "string" } }, "none": { "default": [], "description": "Bio contains none of these.", "type": "array", "items": { "type": "string" } } }, "description": "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\"]}." }, "captionKeywords": { "description": "Words used in recent post captions. Narrows the pool sharply on Instagram/TikTok; add it after bio keywords if needed.", "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "keywords" ] }, "hashtags": { "description": "Instagram and TikTok only. Hashtags without the #, e.g. [\"skincareroutine\"].", "type": "array", "items": { "type": "string" } }, "mostRecentPosts": { "description": "Only creators who posted on or after this date (YYYY-MM-DD). Use to exclude inactive accounts.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "topics": { "description": "Content topics from search_topics, e.g. [\"gaming\"]. Works best on YouTube.", "type": "array", "items": { "type": "string" } }, "minPostCount": { "description": "Minimum number of posts on the account.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxPostCount": { "description": "Maximum number of posts on the account.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "performance": { "default": {}, "description": "Filters on engagement and growth.", "type": "object", "properties": { "averageLikes": { "description": "Average likes per post.", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "averageViews": { "description": "Average views per video/reel.", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "engagementRate": { "description": "Engagement rate in PERCENT, e.g. {minValue: 3} = at least 3%. (Search results report it as engagement_rate_pct, same unit.)", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "audienceGrowth": { "description": "Fast-growing creators: grew at least `percentage`% in the last `interval` months.", "type": "object", "properties": { "interval": { "description": "Lookback window in months, 1-6.", "type": "number" }, "percentage": { "description": "Minimum follower growth in percent over that window.", "type": "number" } } } } }, "page_request_id": { "description": "Use the page_request_id from the previous result for the next paid page; preserve it on retries.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "offset": { "description": "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": 0, "type": "integer", "minimum": 0, "maximum": 490 } }, "required": [ "basic" ] }, "example": { "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 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number", "description": "Total creators matching the filters (not just this page)." }, "preview_creators": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name." }, "handle": { "type": "string", "description": "Username without the @. Pass this to lookup_creator, unlock_creators, get_creator_posts." }, "platform": { "type": "string", "description": "instagram, tiktok or youtube." }, "follower_count": { "type": "number", "description": "Followers (subscribers on YouTube)." }, "engagement_rate_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Engagement rate in percent: 4.5 means 4.5%. Null when unknown." }, "bio": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Profile bio, truncated to about 160 characters." }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the creator is based, when known." }, "is_verified": { "type": "boolean", "description": "Platform verification badge." }, "profile_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Link to the profile on the platform." }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Profile picture URL. Platform CDN links expire after a few days; do not store them long-term." } }, "required": [ "name", "handle", "platform", "follower_count", "engagement_rate_pct", "bio", "location", "is_verified", "profile_url", "photo_url" ], "additionalProperties": false }, "description": "This page: up to 10 creators, in sort order." }, "filters_used": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The filters after defaults were applied. Pass this object as `filters` to run_export to export this exact search." }, "filters_summary": { "type": "string", "description": "Human-readable one-liner of the applied filters." }, "offset": { "type": "number", "description": "Offset of this page." }, "next_offset": { "type": "number", "description": "Offset to request for the next page." }, "page_request_id": { "type": "string", "description": "Opaque id for this page. Not needed for API calls." }, "credits_remaining": { "type": "number", "description": "Account credit balance after this call." }, "estimated_cost_per_creator": { "type": "number", "description": "Credits per creator for an export (currently 1)." }, "max_affordable_count": { "type": "number", "description": "How many creators the current balance could export." }, "source": { "type": "string", "description": "Channel the search was recorded under." }, "usage": { "type": "object", "properties": { "free_creators_per_day": { "type": "number", "description": "Free creators per UTC day across API and MCP (currently 75)." }, "free_creators_left": { "type": "number", "description": "Free creators left today after this call." }, "creators_per_credit": { "type": "number", "description": "Past the free allowance, creators cost 1 credit per this many (currently 4)." }, "usage_pricing": { "type": "boolean", "description": "Whether usage-based pricing is on (Settings → MCP & API). Off = calls stop at the free allowance." }, "creators_returned": { "description": "Creators this call returned.", "type": "number" }, "creators_charged": { "description": "Of those, how many were paid (past the free allowance).", "type": "number" }, "credits_charged": { "description": "Credits this call charged.", "type": "number" } }, "required": [ "free_creators_per_day", "free_creators_left", "creators_per_credit", "usage_pricing" ], "additionalProperties": false, "description": "This account's daily API/MCP allowance, as of this call." }, "suggested_next": { "type": "string", "description": "Plain-English hint written for AI agents calling the API: what to do next. Safe to ignore in code." } }, "required": [ "total", "preview_creators", "filters_used", "filters_summary", "offset", "next_offset", "page_request_id", "credits_remaining", "estimated_cost_per_creator", "max_affordable_count", "source", "suggested_next" ], "additionalProperties": false }, "example": { "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. …" } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analyze_creator_content": { "post": { "operationId": "analyze_creator_content", "summary": "Analyze a creator (lookalike seed)", "description": "Recent captions, hashtags and suggested filters for finding creators similar to one creator.\n\nGive 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.\n\nUntracked creators are fetched live, which can take 10-30 seconds.\n\n**Cost:** Free. A live fetch counts toward the live-refresh rate limit.\n\n**status values:**\n- `ok`: Success.\n- `unavailable`: No posts or bio could be found for this creator. `reason` explains.", "tags": [ "Search" ], "x-credit-cost": "Free. A live fetch counts toward the live-refresh rate limit.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "handle": { "type": "string", "minLength": 2, "maxLength": 64, "description": "Username of the seed creator (a leading @ is fine)." } }, "required": [ "platform", "handle" ] }, "example": { "platform": "instagram", "handle": "example.skinstudio" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "handle": { "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "profile": { "anyOf": [ { "type": "object", "properties": { "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "followers": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "full_name", "bio", "followers", "location" ], "additionalProperties": false }, { "type": "null" } ], "description": "Stored profile, when we track the creator." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "posted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp." }, "post_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "views": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "caption", "posted_at", "post_type", "likes", "views" ], "additionalProperties": false } }, "hashtags": { "type": "array", "items": { "type": "object", "properties": { "tag": { "type": "string" }, "count": { "type": "number" } }, "required": [ "tag", "count" ], "additionalProperties": false }, "description": "Most used hashtags in the recent captions." }, "terms": { "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string" }, "count": { "type": "number" } }, "required": [ "term", "count" ], "additionalProperties": false }, "description": "Salient words and phrases from bio and captions." }, "follower_band": { "description": "Follower range around the creator's size. Absent when the size is unknown.", "type": "object", "properties": { "minValue": { "type": "number" }, "maxValue": { "type": "number" } }, "required": [ "minValue", "maxValue" ], "additionalProperties": false }, "suggested_filters": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Partial search_creators filters to start a lookalike search from." }, "source": { "type": "string", "description": "Where the posts came from: db, live or profile-only." } }, "required": [ "status", "handle", "platform", "profile", "posts", "hashtags", "terms", "suggested_filters", "source" ], "additionalProperties": false }, "example": { "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" } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lookup_creator": { "post": { "operationId": "lookup_creator", "summary": "Look up one creator", "description": "Unlock one creator by profile link or handle and get their contact summary.\n\nResolves 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.\n\nDeep 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.\n\n**Cost:** 1 credit per creator you don't already own. Free if you already unlocked them.\n\n**status values:**\n- `complete`: Success.\n- `insufficient_credits`: 402. 1 credit is needed and the balance is empty.\n- `rate_limited`: 429. Too many live lookups. See retry_after_seconds. Nothing was charged.\n- `error`: 422. The input is not a profile, or the creator could not be loaded (private, missing, wrong platform). `message` explains.", "tags": [ "Creators" ], "x-credit-cost": "1 credit per creator you don't already own. Free if you already unlocked them.", "x-spends-credits": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "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.", "type": "string", "maxLength": 500 }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "handle": { "description": "Username without the @ — the exact handle, never a display name.", "type": "string", "minLength": 1, "maxLength": 80 } } }, "example": { "url": "https://www.instagram.com/example.skinstudio/" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "complete" }, "creator_id": { "type": "string", "description": "Creator Lookup's id for this creator." }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "handle": { "type": "string" }, "creator": { "type": "object", "properties": { "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total_audience": { "description": "Followers across platforms.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "What is already known at return time; enrichment may add more within a minute." }, "charged": { "type": "boolean", "description": "Whether a credit was charged." }, "already_owned": { "type": "boolean", "description": "You had already unlocked this creator." }, "enrichment_running": { "type": "boolean" }, "history_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass to get_history_data or add_to_list." }, "history_url": { "type": "string" }, "note": { "type": "string" } }, "required": [ "status", "creator_id", "platform", "handle", "creator", "charged", "already_owned", "enrichment_running", "history_id", "history_url", "note" ], "additionalProperties": false }, "example": { "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." } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/unlock_creators": { "post": { "operationId": "unlock_creators", "summary": "Unlock selected creators", "description": "Unlock up to 25 hand-picked handles in one call (runs in the background).\n\nUnlock 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.\n\nHandles must be exact usernames (from search results), not display names. Optionally pass `list_name` to also save them to a list (created if missing).\n\n`confirmed` must be `true`. It is a safety latch for AI agents; your code should always send it.\n\n**Cost:** 1 credit per creator you don't already own. Owned creators are free.\n\n**status values:**\n- `processing`: Accepted. Poll get_history_data(history_id).\n- `needs_confirmation`: 400. `confirmed` was not true. Nothing ran.\n- `error`: 422. The batch could not start. `message` explains.", "tags": [ "Creators" ], "x-credit-cost": "1 credit per creator you don't already own. Owned creators are free.", "x-spends-credits": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "handles": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 64 }, "description": "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)." }, "name": { "description": "Label for the history entry, e.g. 'Hand-picked tech fits'.", "type": "string", "maxLength": 100 }, "list_name": { "description": "Also save the unlocked creators into this list (created if it doesn't exist).", "type": "string", "maxLength": 80 }, "confirmed": { "default": false, "description": "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).", "type": "boolean" } }, "required": [ "platform", "handles" ] }, "example": { "platform": "instagram", "handles": [ "example.skinstudio", "example.glowlab" ], "list_name": "Skincare Q4", "confirmed": true } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "processing" }, "history_id": { "type": "string", "description": "Poll get_history_data with this id." }, "history_url": { "type": "string" }, "requested": { "type": "number", "description": "Distinct handles queued." }, "list": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "List id (UUID)." }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The list the creators are being added to, if list_name was given." }, "estimated_seconds": { "type": "number" }, "note": { "type": "string" } }, "required": [ "status", "history_id", "history_url", "requested", "list", "estimated_seconds", "note" ], "additionalProperties": false }, "example": { "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. …" } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/get_creator_posts": { "post": { "operationId": "get_creator_posts", "summary": "Get a creator's recent posts", "description": "Up to 6 recent posts with captions, likes, views and comments.\n\nRecent 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).\n\n**Cost:** Free. A live fetch counts toward the live-refresh rate limit (60/hour, 300/day on paid plans).\n\n**status values:**\n- `ok`: Success.\n- `unavailable`: Posts could not be fetched right now.", "tags": [ "Creators" ], "x-credit-cost": "Free. A live fetch counts toward the live-refresh rate limit (60/hour, 300/day on paid plans).", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "handle": { "type": "string", "minLength": 2, "maxLength": 64, "description": "Username without the @." } }, "required": [ "platform", "handle" ] }, "example": { "platform": "tiktok", "handle": "example.creator" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "handle": { "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "source": { "type": "string", "enum": [ "db", "live" ], "description": "db = stored posts, live = fetched just now." }, "metrics": { "anyOf": [ { "type": "object", "properties": { "avg_likes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg_views": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg_comments": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sampled": { "type": "number" } }, "required": [ "avg_likes", "avg_views", "avg_comments", "sampled" ], "additionalProperties": false }, { "type": "null" } ], "description": "Averages over the posts sampled (null with fewer than 3 posts)." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "posted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp." }, "likes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "views": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "comments": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "post_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Platform CDN links expire; do not store long-term." } }, "required": [ "url", "caption", "posted_at", "likes", "views", "comments", "post_type", "thumbnail" ], "additionalProperties": false } } }, "required": [ "status", "handle", "platform", "source", "metrics", "posts" ], "additionalProperties": false }, "example": { "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" } ] } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/run_export": { "post": { "operationId": "run_export", "summary": "Export a search", "description": "Export the top N creators of a search, with contact details.\n\nRe-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`.\n\nExports 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.\n\nThe balance must cover `limit` credits up front. `confirmed` must be `true` (a safety latch for AI agents).\n\n**Cost:** Up to 1 credit per creator exported; creators you already own are free.\n\n**status values:**\n- `processing`: Accepted. Poll get_history_data(export_id).\n- `complete`: Finished at once (small exports). Read rows with get_history_data(export_id).\n- `insufficient_credits`: 402. The balance does not cover `limit` credits.\n- `needs_confirmation`: 400. `confirmed` was not true. Nothing ran.", "tags": [ "Exports & history" ], "x-credit-cost": "Up to 1 credit per creator exported; creators you already own are free.", "x-spends-credits": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "basic": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "instagram", "youtube", "tiktok" ], "description": "Which network to search. One platform per search." }, "contactDetails": { "description": "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).", "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "PHONE", "LINKTREE", "BBM", "KIK", "SKYPE", "WHATSAPP", "WECHAT", "TELEGRAM", "VIBER", "INSTAGRAM", "YOUTUBE", "TIKTOK", "TWITTER", "SNAPCHAT", "FACEBOOK", "WEIBO", "ITUNES", "KAKAO", "PINTEREST", "LINEID", "TWITCHTV", "SARAHAH", "SAYAT", "TUMBLR", "VK" ] } }, "sortBy": { "description": "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.", "type": "string", "enum": [ "DESCRIPTION", "AVERAGE_LIKE", "AVERAGE_LIKES", "AUDIENCE_LOCATION", "AUDIENCE_LOCATIONS", "AUDIENCE_LANGUAGE", "AUDIENCE_AGE", "AUDIENCE_INTERESTS", "AUDIENCE_LOOKALIKES", "AUDIENCE_BRAND_AFFINITIES", "FOLLOWER_COUNT", "FOLLOWER_GROWTH", "AIRTIME", "ENGAGEMENT_RATE", "TOPIC_RELEVANCE", "AVERAGE_VIEWS", "REELS_VIEWS", "PEAK_VIEWERS", "AVG_CONCURRENT_VIEWERS", "TOTAL_VIEWS_GROWTH", "TOTAL_LIKES_GROWTH", "HOURS_WATCHED", "CREATOR_LOOKALIKES", "CONTENT_COUNT" ] } }, "required": [ "platform" ], "description": "Required. Platform, contact requirement and sort order." }, "creator": { "default": {}, "description": "Filters on the creator themself: size, location, language, demographics.", "type": "object", "properties": { "audienceRange": { "description": "Follower (subscriber) count range, e.g. {minValue: 10000, maxValue: 100000} for micro creators.", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "location": { "description": "Where the CREATOR is based.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Location id from search_locations." }, "display_name": { "type": "string" } }, "required": [ "id" ] }, { "type": "object", "properties": { "name": { "type": "string", "description": "Plain place name, e.g. \"United States\", \"California\", \"London\". Resolved to the best match." } }, "required": [ "name" ] } ] }, "language": { "description": "The language the creator posts in.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "ISO 639-1 language code from search_languages, e.g. \"en\"." }, "name": { "type": "string" } }, "required": [ "code" ] }, { "type": "object", "properties": { "name": { "type": "string", "description": "Language name, e.g. \"Spanish\". Resolved to its code." } }, "required": [ "name" ] } ] }, "gender": { "description": "The creator's gender.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "MALE", "FEMALE" ] } }, "required": [ "code" ] }, "age": { "description": "The creator's age in years.", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "verified": { "description": "{value: true} for verified (blue check) accounts only.", "type": "object", "properties": { "value": { "type": "boolean" } }, "required": [ "value" ] }, "interests": { "description": "Instagram only. Interest names from search_interests, e.g. [\"Fitness & Yoga\"]. Ignored on other platforms.", "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "values" ] }, "accountType": { "description": "Instagram only. Any of PERSONAL, BUSINESS, CREATOR. Ignored on other platforms.", "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" } } }, "required": [ "types" ] }, "lookalikeCreators": { "description": "Platform lookalike filter: a seed creator's username without the @.", "type": "string" } } }, "audience": { "default": {}, "description": "Filters on the creator's followers (audience demographics).", "type": "object", "properties": { "location": { "description": "Where the creator's AUDIENCE (followers) is located.", "type": "object", "properties": { "id": { "description": "Location id from search_locations.", "type": "string" }, "name": { "description": "Plain place name, e.g. \"Germany\". Give id or name.", "type": "string" }, "percentage": { "description": "At least this percent (0-100) of the creator's audience must match.", "type": "number", "minimum": 0, "maximum": 100 } } }, "age": { "description": "The audience's age band.", "type": "object", "properties": { "minValue": { "description": "Youngest age in the band, in years.", "type": "number" }, "maxValue": { "description": "Oldest age in the band, in years.", "type": "number" }, "percentage": { "description": "At least this percent (0-100) of the audience is in the band.", "type": "number", "minimum": 0, "maximum": 100 } } }, "gender": { "description": "The audience's gender split.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "MALE", "FEMALE" ] }, "percentage": { "description": "At least this percent (0-100) of the creator's audience must match.", "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "code" ] }, "language": { "description": "The language the audience speaks.", "type": "object", "properties": { "code": { "description": "ISO 639-1 code from search_languages.", "type": "string" }, "name": { "description": "Language name. Give code or name.", "type": "string" }, "percentage": { "description": "At least this percent (0-100) of the creator's audience must match.", "type": "number", "minimum": 0, "maximum": 100 } } }, "audienceLookalike": { "description": "Username (no @) of a creator whose audience the results' audiences should resemble.", "type": "string" }, "audienceCredibilityScore": { "description": "Minimum share of real (non-bot) followers, 0-1. E.g. 0.8 = at least 80% credible followers.", "type": "number", "minimum": 0, "maximum": 1 } } }, "content": { "default": {}, "description": "Filters on what the creator writes and posts: bio, captions, hashtags, topics, recency.", "type": "object", "properties": { "bioKeywords": { "type": "object", "properties": { "any": { "default": [], "description": "Bio contains at least one of these. The best niche filter on Instagram/TikTok.", "type": "array", "items": { "type": "string" } }, "all": { "default": [], "description": "Bio must also contain every one of these.", "type": "array", "items": { "type": "string" } }, "none": { "default": [], "description": "Bio contains none of these.", "type": "array", "items": { "type": "string" } } }, "description": "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\"]}." }, "captionKeywords": { "description": "Words used in recent post captions. Narrows the pool sharply on Instagram/TikTok; add it after bio keywords if needed.", "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "keywords" ] }, "hashtags": { "description": "Instagram and TikTok only. Hashtags without the #, e.g. [\"skincareroutine\"].", "type": "array", "items": { "type": "string" } }, "mostRecentPosts": { "description": "Only creators who posted on or after this date (YYYY-MM-DD). Use to exclude inactive accounts.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "topics": { "description": "Content topics from search_topics, e.g. [\"gaming\"]. Works best on YouTube.", "type": "array", "items": { "type": "string" } }, "minPostCount": { "description": "Minimum number of posts on the account.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxPostCount": { "description": "Maximum number of posts on the account.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "performance": { "default": {}, "description": "Filters on engagement and growth.", "type": "object", "properties": { "averageLikes": { "description": "Average likes per post.", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "averageViews": { "description": "Average views per video/reel.", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "engagementRate": { "description": "Engagement rate in PERCENT, e.g. {minValue: 3} = at least 3%. (Search results report it as engagement_rate_pct, same unit.)", "type": "object", "properties": { "minValue": { "description": "Inclusive lower bound. Omit for no minimum.", "type": "number" }, "maxValue": { "description": "Inclusive upper bound. Omit for no maximum.", "type": "number" } } }, "audienceGrowth": { "description": "Fast-growing creators: grew at least `percentage`% in the last `interval` months.", "type": "object", "properties": { "interval": { "description": "Lookback window in months, 1-6.", "type": "number" }, "percentage": { "description": "Minimum follower growth in percent over that window.", "type": "number" } } } } } }, "required": [ "basic" ], "description": "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." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many creators to export. REQUIRED — ASK the user how many they want before calling. Never silently export the full match count." }, "format": { "default": "basic", "type": "string", "enum": [ "basic", "full" ] }, "confirmed": { "default": false, "description": "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.", "type": "boolean" } }, "required": [ "filters", "limit" ] }, "example": { "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 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processing", "complete" ] }, "export_id": { "type": "string", "description": "Pass as history_id to get_history_data." }, "history_url": { "type": "string" }, "estimated_seconds": { "description": "processing only.", "type": "number" }, "credits_to_charge": { "description": "processing only: the most this export can charge.", "type": "number" }, "credits_used": { "description": "complete only.", "type": "number" }, "credits_remaining": { "description": "complete only.", "type": "number" }, "creators": { "description": "complete only: always empty; read rows with get_history_data.", "type": "array", "items": {} } }, "required": [ "status", "export_id", "history_url" ], "additionalProperties": false }, "example": { "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 } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/get_history_data": { "post": { "operationId": "get_history_data", "summary": "Get export / unlock results", "description": "Read the creators (with emails) from an export, unlock or lookup. Also the poll for background jobs.\n\nReturns 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.\n\n`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.\n\n**Cost:** Free. These creators are already unlocked.\n\n**status values:**\n- `complete`: Rows are ready.\n- `processing`: The job is still running. Poll again in 30-60 seconds.", "tags": [ "Exports & history" ], "x-credit-cost": "Free. These creators are already unlocked.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "history_id": { "type": "string" }, "detail": { "default": "preview", "description": "preview: name, handle, platform, follower_count, email, country, profile_url. full: same plus all_emails and the raw metadata blob.", "type": "string", "enum": [ "preview", "full" ] }, "limit": { "default": 100, "description": "How many creators to return in this call. Paginate with offset for the rest.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "default": 0, "description": "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).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "history_id" ] }, "example": { "history_id": "5e4d3c2b-1a09-4f8e-9d7c-6b5a4f3e2d1c", "detail": "preview", "limit": 100, "offset": 0 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "processing" ] }, "history_url": { "type": "string" }, "creators": { "description": "complete only.", "type": "array", "items": { "type": "object", "properties": { "rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Position in the search order (1 = first)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Username on `platform`." }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "follower_count": { "type": "number" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Primary business email, when one was found." }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_niche": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "profile_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "all_emails": { "description": "detail=full only: every email found for the creator.", "type": "array", "items": { "type": "string" } }, "raw_metadata": { "description": "detail=full only: the full stored profile (cross-platform usernames, links, stats). Shape may grow over time." } }, "required": [ "rank", "name", "handle", "platform", "follower_count", "email", "country", "state", "city", "primary_niche", "profile_url" ], "additionalProperties": {} } }, "total_count": { "description": "complete only: creators in the whole job.", "type": "number" }, "returned": { "description": "complete only: creators in this page.", "type": "number" }, "offset": { "type": "number" }, "has_more": { "description": "complete only: call again with offset + returned.", "type": "boolean" }, "filters_used": { "description": "complete only: the search that produced this job, when there was one." }, "estimated_seconds_remaining": { "description": "processing only.", "type": "number" } }, "required": [ "status", "history_url" ], "additionalProperties": false }, "example": { "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 } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/list_search_history": { "post": { "operationId": "list_search_history", "summary": "List search history", "description": "Your recent searches and exports, newest first.\n\nThe same history the app shows under Creators → History. Use an item's `id` as `history_id` for get_history_data or add_to_list.\n\n**Cost:** Free.\n\n**status values:**\n- `(absent)`: Success.", "tags": [ "Exports & history" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "default": "all", "type": "string", "enum": [ "all", "searches", "exports" ] } } }, "example": { "kind": "exports", "limit": 10, "offset": 0 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "history_id." }, "kind": { "type": "string", "enum": [ "search", "export" ] }, "filters_summary": { "type": "string" }, "total": { "type": "number", "description": "Creators in the result." }, "status": { "type": "string", "description": "SUCCESS, PROCESSING, FAILED, …" }, "created_at": { "type": "string", "description": "ISO 8601." }, "source": { "type": "string", "description": "Where it was made: web, ai_mode, mcp." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "kind", "filters_summary", "total", "status", "created_at", "source", "name" ], "additionalProperties": false } }, "total_count": { "type": "number", "description": "Items matching `kind` (for pagination)." } }, "required": [ "items", "total_count" ], "additionalProperties": false }, "example": { "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 } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/get_lists": { "post": { "operationId": "get_lists", "summary": "Get lists", "description": "Your creator lists with counts.\n\nAll of the account's creator lists. Lists are also visible in the app under Creators → Lists.\n\n**Cost:** Free.\n\n**status values:**\n- `(absent)`: Success.", "tags": [ "Lists" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "List id (UUID)." }, "name": { "type": "string" }, "url": { "type": "string", "description": "The list in the Creator Lookup app." }, "creator_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "name", "url", "creator_count" ], "additionalProperties": false } }, "note": { "type": "string" } }, "required": [ "lists", "note" ], "additionalProperties": false }, "example": { "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." } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/create_list": { "post": { "operationId": "create_list", "summary": "Create a list", "description": "Create a creator list (returns the existing one if the name is taken).\n\nCreates a list by name. If a list with that name (case-insensitive) exists, it is returned instead.\n\n**Cost:** Free.\n\n**status values:**\n- `ok`: Success.\n- `error`: 422. The list could not be created.", "tags": [ "Lists" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "List name, e.g. 'Cold brew UGC shortlist'." } }, "required": [ "name" ] }, "example": { "name": "Skincare Q4" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "list": { "type": "object", "properties": { "id": { "type": "string", "description": "List id (UUID)." }, "name": { "type": "string" }, "url": { "type": "string", "description": "The list in the Creator Lookup app." }, "creator_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "name", "url", "creator_count" ], "additionalProperties": false } }, "required": [ "status", "list" ], "additionalProperties": false }, "example": { "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" } } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/add_to_list": { "post": { "operationId": "add_to_list", "summary": "Add creators to a list", "description": "Add every creator from an export, unlock or lookup to a list.\n\nAdds 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.\n\n**Cost:** Free. The creators are already unlocked.\n\n**status values:**\n- `ok`: Success.\n- `empty`: The history entry has no creators yet (still processing?).\n- `error`: 422. `message` explains.", "tags": [ "Lists" ], "x-credit-cost": "Free. The creators are already unlocked.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Target list, by name or id. Created automatically if it doesn't exist." }, "history_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "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." } }, "required": [ "list", "history_id" ] }, "example": { "list": "Skincare Q4", "history_id": "5e4d3c2b-1a09-4f8e-9d7c-6b5a4f3e2d1c" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "list": { "type": "object", "properties": { "id": { "type": "string", "description": "List id (UUID)." }, "name": { "type": "string" }, "url": { "type": "string", "description": "The list in the Creator Lookup app." } }, "required": [ "id", "name", "url" ], "additionalProperties": false }, "added": { "type": "number", "description": "Creators added." } }, "required": [ "status", "list", "added" ], "additionalProperties": false }, "example": { "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 } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/get_list_creators": { "post": { "operationId": "get_list_creators", "summary": "Get list creators", "description": "The creators saved in a list, with contact details.\n\nPages through one list (by name or id), 100 creators per call at most.\n\n**Cost:** Free.\n\n**status values:**\n- `ok`: Success.\n- `not_found`: 404. No list with that name or id.", "tags": [ "Lists" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "string", "minLength": 1, "maxLength": 80, "description": "List name or id." }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "list" ] }, "example": { "list": "Skincare Q4", "limit": 20, "offset": 0 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "list": { "type": "object", "properties": { "id": { "type": "string", "description": "List id (UUID)." }, "name": { "type": "string" }, "url": { "type": "string", "description": "The list in the Creator Lookup app." } }, "required": [ "id", "name", "url" ], "additionalProperties": false }, "creators": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total_audience": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Followers across platforms." }, "total_reach": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platforms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "metadata": { "description": "Full stored profile (usernames, links, stats per platform)." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "full_name", "primary_email", "phone", "gender", "country", "state", "city", "language", "total_audience", "total_reach", "avatar_url", "platforms", "metadata", "created_at", "updated_at" ], "additionalProperties": {} } } }, "required": [ "status", "list", "creators" ], "additionalProperties": false }, "example": { "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" } ] } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search_locations": { "post": { "operationId": "search_locations", "summary": "Search locations", "description": "Look up location ids (countries, states, cities) for location filters.\n\nAutocomplete for `creator.location` and `audience.location`. Plain names also work in filters; use this when you need an exact id.\n\n**Cost:** Free.\n\n**status values:**\n- `(absent)`: Success.", "tags": [ "Filter values" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "limit": { "default": 12, "type": "integer", "minimum": 1, "maximum": 30 } }, "required": [ "query" ] }, "example": { "query": "texas", "limit": 3 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "type": { "description": "COUNTRY, STATE, CITY, …", "type": "string" } }, "required": [ "id", "display_name" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "id": "c3f1e0a2-0000-0000-0000-000000000000", "display_name": "Texas, United States", "type": "STATE" } ] } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search_languages": { "post": { "operationId": "search_languages", "summary": "Search languages", "description": "Look up language codes for language filters.\n\nAutocomplete for `creator.language` and `audience.language`.\n\n**Cost:** Free.\n\n**status values:**\n- `(absent)`: Success.", "tags": [ "Filter values" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "default": "", "type": "string" }, "limit": { "default": 12, "type": "integer", "minimum": 1, "maximum": 30 } } }, "example": { "query": "span", "limit": 3 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "code": "es", "name": "Spanish" } ] } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search_interests": { "post": { "operationId": "search_interests", "summary": "Search interests", "description": "Interest names for the Instagram interests filter.\n\nValues for `creator.interests.values` (Instagram only).\n\n**Cost:** Free.\n\n**status values:**\n- `(absent)`: Success.", "tags": [ "Filter values" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "default": "", "type": "string" }, "limit": { "default": 12, "type": "integer", "minimum": 1, "maximum": 30 } } }, "example": { "query": "fit", "limit": 3 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "name": "Fitness & Yoga" } ] } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search_topics": { "post": { "operationId": "search_topics", "summary": "Search topics", "description": "Topic names for the topics filter (best on YouTube).\n\nValues for `content.topics`.\n\n**Cost:** Free.\n\n**status values:**\n- `(absent)`: Success. On a lookup failure `items` is empty and `error` is set.", "tags": [ "Filter values" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "default": "", "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "youtube", "tiktok" ] }, "limit": { "default": 12, "type": "integer", "minimum": 1, "maximum": 30 } } }, "example": { "query": "gaming", "platform": "youtube", "limit": 3 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "error": { "type": "string" } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "name": "gaming", "value": "gaming" } ] } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search_handles": { "post": { "operationId": "search_handles", "summary": "Search handles", "description": "Find creator usernames by partial handle or name.\n\nUseful for `creator.lookalikeCreators`, `audience.audienceLookalike`, or to check an exact handle before lookup_creator.\n\n**Cost:** Free.\n\n**status values:**\n- `(absent)`: Success. On a lookup failure `items` is empty and `error` is set.", "tags": [ "Filter values" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "instagram", "youtube", "tiktok" ] }, "limit": { "default": 8, "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "query" ] }, "example": { "query": "example", "platform": "instagram", "limit": 3 } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string" }, "full_name": { "type": "string" }, "followers": { "type": "number" } }, "required": [ "handle" ], "additionalProperties": false } }, "error": { "type": "string" } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "handle": "example.skinstudio", "full_name": "Example Skin Studio", "followers": 48210 } ] } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/get_credit_balance": { "post": { "operationId": "get_credit_balance", "summary": "Get credit balance", "description": "Credit balance, plan, and how API searches are billed.\n\nThe account's credit balance and its API/MCP billing settings. A good first call to check your key works.\n\n**Cost:** Free.\n\n**status values:**\n- `(absent)`: Success.", "tags": [ "Account" ], "x-credit-cost": "Free.", "x-spends-credits": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "number", "description": "Credits available." }, "plan": { "type": "string" }, "trial": { "type": "boolean" }, "mcp_api": { "type": "object", "properties": { "free_creators_per_day": { "type": "number" }, "creators_per_credit": { "type": "number" }, "usage_pricing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Usage-based pricing on/off (null if it could not be read)." }, "settings_url": { "type": "string" }, "note": { "type": "string" } }, "required": [ "free_creators_per_day", "creators_per_credit", "usage_pricing", "settings_url", "note" ], "additionalProperties": false } }, "required": [ "balance", "plan", "trial", "mcp_api" ], "additionalProperties": false }, "example": { "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: …" } } } } }, "400": { "description": "Invalid body (`invalid_request`) or missing `confirmed: true` (`needs_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`usage_pricing_required` or `insufficient_credits`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`api_access_requires_plan` or `account_suspended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`error`: valid request that could not be completed; see `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`; see the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key from Settings → MCP & API." } }, "schemas": { "Error": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "invalid_request only: one entry per invalid field.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } }, "retry_after": { "type": "number", "description": "rate_limited only: seconds to wait, when known." } }, "additionalProperties": true } } } }