Using Natural Language Search

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).

Headers

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
}

The 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"
  }'

Response (final result event):

{
  "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"
  }'

Response (final result event):

{
  "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"
  }'

Response (final result event):

{
  "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.

Getting Started

User Guides

API Endpoints

Filter Value References

Troubleshooting and FAQs

How it works

Endpoint

Request body

Headers

Streaming response

Progress events

Result event — creator results

Result event — suggestions

Credit cost

Examples

Find YouTube beauty creators

Find Instagram sustainable fashion influencers

Find TikTok cooking creators

Tips for better queries

​How it works

​Endpoint

​Request body

​Headers

​Streaming response

​Progress events

​Result event — creator results

​Result event — suggestions

​Credit cost

​Examples

​Find YouTube beauty creators

​Find Instagram sustainable fashion influencers

​Find TikTok cooking creators

​Tips for better queries

How it works

Endpoint

Request body

Headers

Streaming response

Progress events

Result event — creator results

Result event — suggestions

Credit cost

Examples

Find YouTube beauty creators

Find Instagram sustainable fashion influencers

Find TikTok cooking creators

Tips for better queries