Authentication
Authenticate requests with your API key using the following HTTP header.
Authorization: Bearer <YOUR_KEY>API access requires a paid workspace. Calls are billed by usage.
POST/api/openapi/v1/creators/ai-searchAI search
Instagram / YouTube / TikTok0.5 credits / creator
Twitter / X2 credits / creator
Reserve the requested count; charge only returned creators. Failures are refunded. TikTok only: filters.videoCartOnly=true defaults to false and adds 1 credit per returned creator (currently 1.5 credits total). Matches stored shopping-cart evidence, not live product availability.
Supported platformsInstagram / YouTube / TikTok / Twitter / X
Quick start (cURL)
curl -X POST 'https://app.hicreator.ai/api/openapi/v1/creators/ai-search' \
-H 'Authorization: Bearer <YOUR_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"platform": "instagram",
"query": "Home cooking creators sharing simple, healthy recipes",
"limit": 40,
"filters": {
"regions": [
"US",
"GB"
],
"excludedRegions": [
"DE"
],
"languages": [
"en"
],
"minFollowers": 50000,
"maxFollowers": 500000,
"minPlayCount": 10000,
"playCountMetric": "median",
"creatorTypes": [
"solo_creator"
],
"faceVisibilities": [
"clear_face",
"partial_face"
],
"workspaceDeduplicationEnabled": true
}
}'Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| filters.videoCartOnly | boolean | No | TikTok only: filters.videoCartOnly=true defaults to false and adds 1 credit per returned creator (currently 1.5 credits total). Matches stored shopping-cart evidence, not live product availability.View allowed valuestiktok |
| platform | string | Yes | Creator platform.View allowed valuesinstagram / youtube / tiktok / twitter |
| query | string | Yes | Describe the creators you want to find. |
| limit | integer | No | Number of creators; default 40, maximum 100. |
| filters | object | No | Search filters. |
| filters.regions | string[] | No | Countries or regions to include, e.g. US or GB. |
| filters.excludedRegions | string[] | No | Countries or regions to exclude. |
| filters.languages | string[] | No | Content languages; use zh-Hans or zh-Hant for Chinese.View allowed valuesen / es / pt / fr / de / ko / ja / ar / ru / it / zh-Hant / tr / id / hi / pl / vi / th / nl / fa / zh-Hans / bn / da / uk / ro / sv / el / ms / cs / he / hu / mr / fi / sr / hr / ml / no / ta / tl / zh |
| filters.minFollowers / maxFollowers | integer | No | Follower count range. |
| filters.minPlayCount / maxPlayCount | integer | No | Video play count range. Video platforms only. |
| filters.playCountMetric | string | No | average (default) or median. Video platforms only. |
| filters.genders | string[] | No | Gender.View allowed valuesfemale / male |
| filters.ethnicities | string[] | No | Ethnicity.View allowed valueswhite / black / asian / hispanic_latino / middle_eastern / indigenous / pacific_islander / multiracial |
| filters.creatorTypes | string[] | No | Creator type. Video platforms only.View allowed valuessolo_creator / couple / family / group / product_only / brand_account / media_publisher / organization / content_aggregator / virtual_creator |
| filters.faceVisibilities | string[] | No | Face visibility. Video platforms only.View allowed valuesclear_face / partial_face / no_face / mixed |
| filters.twitter | object | No | Twitter / X filters. |
| filters.twitter.accountTypes | string[] | No | Account type.View allowed valuesperson / brand / company / media / organization / community / aggregator / bot / unknown |
| filters.twitter.ageRanges | string[] | No | Age range.View allowed values0_17 / 18_24 / 25_34 / 35_44 / 45_54 / 55_64 / 65_plus / unknown / not_applicable |
| filters.twitter.minViewCount / maxViewCount | integer | No | Post view count range. |
| filters.twitter.viewCountMetric | string | No | average (default) or median. |
| filters.twitter.minFollowingCount / maxFollowingCount | integer | No | Following count range. |
| filters.twitter.originalPublishedWithinDays | integer | No | Original posts published within this many days (1–30). |
| filters.twitter.activeWithinDays | integer | No | Active within this many days (1–365). |
| filters.twitter.capturedWithinDays | integer | No | Profile captured within this many days (1–365). |
| filters.workspaceDeduplicationEnabled | boolean | No | Exclude past searches when enabled; exclusions always apply. |
Response fields
| Parameter | Type | Always returned | Description |
|---|---|---|---|
| requestId | string | Yes | Request ID for support. |
| billingRequestId | string | Yes | Billing record ID. |
| data | object | Yes | Query result. |
| data.items | object[] | Yes | Creator list. |
| data.count | integer | Yes | Returned creator count. |
| data.items[].id | string | Yes | Platform creator ID. |
| data.items[].username | string | Yes | Handle. |
| data.items[].fullName | string | null | Yes | Display name. |
| data.items[].platform | string | Yes | Platform. |
| data.items[].biography | string | null | Yes | Biography. |
| data.items[].followerCount | integer | null | Yes | Followers or subscribers. |
| data.items[].region | string | null | Yes | Region. |
| data.items[].language | string | null | Yes | Primary content language. |
| data.items[].email | string | null | Yes | Public contact email. |
| data.items[].averagePlayCount | number | null | Yes | Average plays. |
| data.items[].medianPlayCount | number | null | Yes | Median plays. |
| data.items[].averageEngagementRate | number | null | Yes | Average engagement rate as a decimal. |
| data.items[].medianEngagementRate | number | null | Yes | Median engagement rate as a decimal. |
| data.items[].gender | string | null | Yes | Gender. |
| data.items[].ageRange | string | null | Yes | Age range. |
| data.items[].ethnicity | string | null | Yes | Ethnicity. |
| data.items[].faceVisibility | string | null | Yes | Face visibility. |
| data.items[].accountPositioning | string[] | Yes | Profile positioning tags. |
| data.items[].aiDescription | string | null | Yes | AI creator summary. |
| data.items[].profileUrl | string | Yes | Creator profile link. |
| data.items[].score | number | Yes | Match score; higher is more relevant. |
Example response (JSON)
{
"requestId": "<request-id>",
"billingRequestId": "<billing-request-id>",
"data": {
"items": [
{
"id": "<creator-id>",
"username": "example_creator",
"fullName": "<creator-name>",
"platform": "instagram",
"biography": "<creator-biography>",
"followerCount": 50000,
"region": "US",
"language": "en",
"email": "[email protected]",
"averagePlayCount": 12000,
"medianPlayCount": 9800,
"averageEngagementRate": 0.045,
"medianEngagementRate": 0.041,
"gender": "female",
"ageRange": "25-34",
"ethnicity": "asian",
"faceVisibility": "clear_face",
"accountPositioning": [
"<account-positioning>"
],
"aiDescription": "<ai-description>",
"profileUrl": "https://www.instagram.com/example_creator/",
"score": 0.82
}
],
"count": 1
}
}Errors and retries
See error.message; keep requestId for support. Do not retry uncertain requests.
View error codes
Request: 400 invalid parameters (10001) or quantity below the minimum (70004); 401 invalid key (20001); 403 API access is only available to paid Workspaces (60006); 413 payload too large (10005); 415 unsupported format (10006); 429 too many requests (10007).
Execution: 404 Twitter creator unavailable (60008); 422 invalid search intent (60001) or target account (60002); 422 email lookup incomplete (60009): search limits reached, fully refunded; this does not mean no email exists and must not be automatically retried; 502 email lookup failed (60003) or execution failed (60004); 504 request timed out (60005). Gateway error pages are returned as JSON with code API_UPSTREAM_ERROR; do not automatically retry paid requests.
Credits: 402 insufficient balance (70001) or daily limit exceeded (70006); 409 feature unavailable (70002) or credit record conflict (70003). API errors include error.code, error.message, and error.requestId. Business errors include error.billingRequestId after charging starts; gateway fallbacks may lack it and cannot confirm refund status.