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

# Using Natural Language Search

> Search for YouTube, Instagram, and TikTok creators using natural language descriptions

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.

<Note>
  NLS uses Server-Sent Events (SSE) streaming. You'll receive progress updates as the query is processed, followed by the final results.
</Note>

## Endpoint

```http theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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

```bash theme={null}
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):

```json theme={null}
{
  "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

```bash theme={null}
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):

```json theme={null}
{
  "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

```bash theme={null}
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):

```json theme={null}
{
  "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.

<Warning>
  NLS returns a maximum of 20 creators per query. For larger result sets, use the [search endpoint](/api-v3/configuring_advanced_search_filters) with structured filters.
</Warning>