Search for creators by describing what you’re looking for in plain language. The CreatorDB API converts your description into structured search filters and returns matching creators.
How it works
Send a POST request to /nls with a description field. The AI analyzes your query, determines the appropriate platform (YouTube, Instagram, or TikTok), and returns matching creators.
You don’t need to specify a platform — the API detects it from your query. For example, “YouTube gaming creators with 1M subscribers” automatically searches YouTube, while “Instagram fashion influencers in Japan” searches Instagram.
NLS uses Server-Sent Events (SSE) streaming. You’ll receive progress updates as the query is processed, followed by the final results.
Endpoint
POST https://apiv3.creatordb.app/nls
Request body
| Parameter | Type | Required | Description |
|---|
description | string | Yes | A natural language description of the creators you’re looking for (1–1000 characters). |
| Header | Value |
|---|
Content-Type | application/json |
api-key | Your API key |
Streaming response
The response is delivered as a stream of Server-Sent Events (SSE). Each event has a type and a JSON data payload.
Progress events
While the query is being processed, you’ll receive progress updates:
event: progress
data: {"message": "Analyzing your query..."}
event: progress
data: {"message": "Searching for creators..."}
Result event — creator results
When matching creators are found, the final event contains the results:
event: result
data: {
"data": {
"creatorList": [
{
"displayName": "James Charles",
"uniqueId": "@jamescharles",
"channelId": "UCucot-Zp428OwkyRm2I7v2Q",
"avatarUrl": "https://yt3.googleusercontent.com/...",
"totalSubscribers": 24000000
}
],
"platform": "youtube"
},
"creditsUsed": 3,
"creditsAvailable": 997,
"traceId": "02a03542233eff21e4a781c9a5090e18",
"timestamp": 1770099403116,
"errorCode": "",
"errorDescription": "",
"success": true
}
platform field tells you which platform the AI selected based on your query.
Result event — suggestions
If your query is too broad or ambiguous, the API returns suggestions instead of results:
event: result
data: {
"data": {
"message": "Your query is too broad to return specific results. Try narrowing your search.",
"suggestion": [
"Try: US-based beauty YouTubers with over 1M subscribers",
"Try: Instagram fashion influencers in Japan with 500K+ followers",
"Try: TikTok comedy creators with high engagement rates"
]
},
"creditsUsed": 1,
"creditsAvailable": 999,
"traceId": "a1b2c3d4e5f6",
"timestamp": 1770099403116,
"errorCode": "",
"errorDescription": "",
"success": true
}
Credit cost
NLS uses dynamic, token-based pricing. The cost depends on the complexity of your query and the AI processing required. Typical queries cost 2–4 credits.
Examples
Find YouTube beauty creators
curl -X POST "https://apiv3.creatordb.app/nls" \
--header 'Content-Type: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
"description": "Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers"
}'
{
"data": {
"creatorList": [
{
"displayName": "James Charles",
"uniqueId": "@jamescharles",
"channelId": "UCucot-Zp428OwkyRm2I7v2Q",
"avatarUrl": "https://yt3.googleusercontent.com/...",
"totalSubscribers": 24000000
},
{
"displayName": "Troom Troom",
"uniqueId": "@troomtroom",
"channelId": "UCWwqHwqLSrdWMgp5DZG5Dzg",
"avatarUrl": "https://yt3.googleusercontent.com/...",
"totalSubscribers": 23900000
}
],
"platform": "youtube"
},
"creditsUsed": 3,
"creditsAvailable": 997,
"traceId": "02a03542233eff21e4a781c9a5090e18",
"timestamp": 1770099403116,
"errorCode": "",
"errorDescription": "",
"success": true
}
Find Instagram sustainable fashion influencers
curl -X POST "https://apiv3.creatordb.app/nls" \
--header 'Content-Type: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
"description": "Looking for Instagram fashion influencers who focus on sustainable clothing, with at least 500K followers, primarily targeting female audiences aged 18-24 in the USA"
}'
{
"data": {
"creatorList": [
{
"displayName": "THE ZERO WASTE GUIDE by Allott",
"uniqueId": "thezerowasteguide",
"avatarUrl": "https://scontent.cdninstagram.com/...",
"totalFollowers": 709115
},
{
"displayName": "Sophie Webb",
"uniqueId": "what.sophie.does",
"avatarUrl": "https://scontent.cdninstagram.com/...",
"totalFollowers": 987172
}
],
"platform": "instagram"
},
"creditsUsed": 4,
"creditsAvailable": 993,
"traceId": "f8e4a3b2c1d0e9f8a7b6c5d4",
"timestamp": 1770099503200,
"errorCode": "",
"errorDescription": "",
"success": true
}
Find TikTok cooking creators
curl -X POST "https://apiv3.creatordb.app/nls" \
--header 'Content-Type: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
"description": "TikTok cooking creators in Korea who make short recipe videos with over 2 million followers"
}'
{
"data": {
"creatorList": [
{
"displayName": "Recipe Example",
"uniqueId": "recipeexample",
"avatarUrl": "https://p16-sign.tiktokcdn.com/...",
"totalFollowers": 2500000
}
],
"platform": "tiktok"
},
"creditsUsed": 2,
"creditsAvailable": 991,
"traceId": "c4d5e6f7a8b9c0d1",
"timestamp": 1770099603300,
"errorCode": "",
"errorDescription": "",
"success": true
}
Tips for better queries
- Be specific about the platform — include “YouTube”, “Instagram”, or “TikTok” in your query for faster, more accurate results.
- Include measurable criteria — subscriber/follower thresholds, engagement rates, or content frequency give the AI concrete filters to apply.
- Describe the audience — specifying audience demographics (age, gender, location) helps narrow results.
- Mention content themes — terms like “tech review”, “sustainable fashion”, or “cooking tutorials” help the AI classify the niche.
- Keep queries under a few sentences — concise descriptions work better than long paragraphs. The maximum is 1000 characters.
NLS returns a maximum of 20 creators per query. For larger result sets, use the search endpoint with structured filters. 
