Documentation Index
Fetch the complete documentation index at: https://docs.creatordb.app/llms.txt
Use this file to discover all available pages before exploring further.
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. 
