> ## 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 Creators by Prompt > Search for creators across YouTube, Instagram, and TikTok using natural language descriptions. The AI determines the appropriate platform from your query and converts it into structured search filters. Results are delivered via Server-Sent Events (SSE) streaming. ## OpenAPI ````yaml /api-v3/api-v3.yaml post /nls openapi: 3.1.0 info: version: 1.0.0 title: CreatorDB Headless API V3 description: '# CreatorDB Headless API V3' contact: name: CreatorDB url: https://www.creatordb.app email: support@creatordb.app license: url: http://www.apache.org/licenses/LICENSE-2.0.html name: Apache 2.0 servers: - url: https://apiv3.creatordb.app description: Production Environment (CreatorDB Headless API V3) security: - ApiKeyAuth: [] tags: - name: Brand description: Brand analysis endpoints including sponsor search and brand reports. - name: Facebook description: Facebook creator data endpoints with metrics and search capabilities. - name: General Operations description: >- General-purpose endpoints such as API status, content retrieval, and cross-platform operations. - name: Instagram description: >- Instagram creator data endpoints with metrics and advanced search capabilities. - name: Niches description: >- Niche-related endpoints for content category analysis and related searches. - name: Threads description: Threads creator data endpoints with basic metrics and historical data. - name: TikTok description: >- TikTok creator data endpoints with metrics and advanced search functionality. - name: Topic description: Topic-based analysis and reporting endpoints for content categorization. - name: YouTube description: >- YouTube creator data endpoints including basic metrics, historical data, and detailed analytics. paths: /nls: post: tags: - AI Search summary: Search Creators by Prompt description: >- Search for creators across YouTube, Instagram, and TikTok using natural language descriptions. The AI determines the appropriate platform from your query and converts it into structured search filters. Results are delivered via Server-Sent Events (SSE) streaming. operationId: getNLS requestBody: required: true content: application/json: schema: type: object description: Natural language search parameters. properties: description: type: string description: >- A natural language description of the creators you are looking for. minLength: 1 maxLength: 1000 example: >- Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers required: - description responses: '200': description: >- NLS results are delivered via Server-Sent Events (SSE). The stream emits multiple `event: progress` messages with status updates (e.g., `{"message":"Loading..."}`, `{"message":"Analyzing intent..."}`, `{"message":"Query ready..."}`), followed by a final `event: result` containing the response object shown below. Connect using an SSE-capable client or `stream=True` in your HTTP library. content: text/event-stream: schema: type: object properties: data: type: object properties: creatorList: type: array description: >- Matching creators. Present when the query returns results. items: type: object properties: displayName: type: string description: The creator display name. uniqueId: type: string description: The creator handle. channelId: type: string description: YouTube channel ID. avatarUrl: type: string description: Profile picture URL. totalSubscribers: type: integer description: YouTube subscriber count. totalFollowers: type: integer description: Instagram or Tiktok follower count. platform: type: string description: The platform detected from the query. enum: - youtube - instagram - tiktok message: type: string description: >- Explanation when the query is too broad (suggestion response). suggestion: type: array items: type: string description: >- Refined query suggestions when the original query is too broad. creditsUsed: type: number description: >- Credits consumed for this request (dynamic, based on token usage). examples: - 3.04 creditsAvailable: type: number description: Number of API credits remaining. examples: - 2627.89 traceId: type: string description: Unique trace ID for each request. examples: - 6ddf6c22a7a84b83e9a98f70a06e6235 timestamp: type: integer description: >- Time the response was generated, represented as a Unix timestamp in milliseconds. examples: - 1774586488186 errorCode: type: string description: >- Error code returned if the request fails. Empty if the request is successful. examples: - '' errorDescription: type: string description: >- Description of the error. Empty if the request is successful. examples: - '' success: type: boolean description: '`true` if the request is successful.' examples: - true required: - data - traceId - timestamp - errorCode - errorDescription - success - creditsUsed - creditsAvailable examples: default: summary: SSE stream with progress events and final result value: - event: progress data: message: Loading... - event: progress data: message: Query validated... - event: progress data: message: Analyzing intent... - event: progress data: message: Processing request... - event: progress data: message: Identifying filters... - event: progress data: message: Working on it... - event: progress data: message: Getting the right filters... - event: progress data: message: Analysis complete... - event: progress data: message: Putting it all together... - event: progress data: message: Building query... - event: progress data: message: Query ready... - event: result data: creatorList: - displayName: YouTube uniqueId: '@youtube' channelId: UCBR8-60-B28hp2BmDPdntcQ avatarUrl: >- https://yt3.googleusercontent.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 45000000 - displayName: 5-Minute Crafts DIY uniqueId: '@5minutecraftsdiy' channelId: UC2etEuPIfohP4P53wM0KImA avatarUrl: >- https://yt3.googleusercontent.com/dpw85Qj9vAdE4iX_yr0wUcoZkuBZqPBrlovIkePsgOzmywZdQeJpUQARG1to6mEEeqmUQlMtR-o=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 20100000 - displayName: 5-Minute Crafts FAMILY uniqueId: '@5minutecraftsfamily' channelId: UC63mNFJR8EAb8wAIJwoCmTA avatarUrl: >- https://yt3.googleusercontent.com/jPrniMECPSuIG45SMTj4VlCxtYqQ4E4RqnZIPxJPPhm_mb1ZHV2X0MFwCh3X6R_3lLvIooVxbNE=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 15800000 - displayName: Kids Diana Show uniqueId: '@kidsdianashow' channelId: UCk8GzjMOrta8yxDcKfylJYw avatarUrl: >- https://yt3.googleusercontent.com/G88LBGqFoBWMos0glZEdCvQ7uEMPnhBYsPRMOFX5b5z6tuqWaD6ZcscslaKu0zLO37v8sMUA=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 138000000 - displayName: Maria Clara & JP uniqueId: '@mariaclaraejp' channelId: UCKe6w0exI94U-RzqAyoY1VA avatarUrl: >- https://yt3.googleusercontent.com/ytc/AIdro_n8EDt3qdYql9Dt6WAZDlb_7Af8wIukpc3h3cAbCptHNUg=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 50200000 - displayName: Mr DegrEE uniqueId: '@mrdegreeofficial' channelId: UCeYTfGpNCmVhlxjQxBDrGPA avatarUrl: >- https://yt3.googleusercontent.com/ytc/AIdro_k8LXkXtQX2Skbr0NZ2jzNO-_j-Bu2T80hWwDUs3eL2ZCg=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 40400000 - displayName: SMOL uniqueId: '@smol_official' channelId: UCBBZ7No0AzEJ3qiatjSa-mg avatarUrl: >- https://yt3.googleusercontent.com/QSq4dqpufwELLxjadoLE8CghxJ12tfu4vGUM8t2YiwztzAyYtPvSKN59nH_lEd02vPQfnQ3L2Q=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 27200000 - displayName: Fabiosa Best Lifehacks uniqueId: '@fabiosabestlifehacks' channelId: UCF5Rp2ghzXsX6vwYqa7aepg avatarUrl: >- https://yt3.googleusercontent.com/g9YIHarU8-wUSH5lnFRNg9e9RBT9EHv21rlP7r10lHwmpALsDzt-jiSkVzBxTUyDBQjK3Hz1hA=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 25900000 - displayName: James Charles uniqueId: '@jamescharles' channelId: UCucot-Zp428OwkyRm2I7v2Q avatarUrl: >- https://yt3.googleusercontent.com/6WC8rRE_1ME7Sza7y-Z75g_wGahOKlyRevH2hOE9DNMrHM37ZYCmNGBnJpJWqhUpy0-c05xQcjk=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 23900000 - displayName: Troom Troom uniqueId: '@troomtroom' channelId: UCWwqHwqLSrdWMgp5DZG5Dzg avatarUrl: >- https://yt3.googleusercontent.com/KxkUWubksdvmkXC6dKk_JuJF40McZgmDYWcclmNJHAuhDnZGpVA9-sdW75q9MTCZ-NE2z3yBfY0=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 23800000 - displayName: Marusya Outdoors uniqueId: '@marusya_outdoors' channelId: UCRR3vpGoVKF3q_vZI7mCfjQ avatarUrl: >- https://yt3.googleusercontent.com/JNVo_OhRKlrCe4lTIehltRomjHGhAwADSeliVky8KSpwqfeaZ2Y7QCCUiOPVIfFt6XLzCwNE=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 20600000 - displayName: Dr Ryan uniqueId: '@itsdrryan' channelId: UC26FEMwAAjj8jfNbuVdFMBQ avatarUrl: >- https://yt3.googleusercontent.com/8XsSINxf0myiTvCb-KByq8eLOQMDg7en6Mxdap1YlbddXyvyBypr5lCaSi98KJhSOCwD9z5gxQ=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 20000000 - displayName: VICE uniqueId: '@vice' channelId: UCn8zNIfYAQNdrFRrr8oibKw avatarUrl: >- https://yt3.googleusercontent.com/9AgWUnohXk3gFYvmvAZemlr1q6yd7NxHozeEqrPpJhYf9Crjrvqml0ulZ4PL4v38I4XDoLEhaw=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 19100000 - displayName: Crafty Panda uniqueId: '@craftypanda' channelId: UC03RvJoIhm_fMwlUpm9ZvFw avatarUrl: >- https://yt3.googleusercontent.com/ytc/AIdro_kI-gjxVAiZh-LDX0ayqKKSQL-qIxrCG7qi3Q2IQNeTamk=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 19000000 - displayName: Ray William Johnson uniqueId: '@raywilliamjohnson' channelId: UCGt7X90Au6BV8rf49BiM6Dg avatarUrl: >- https://yt3.googleusercontent.com/y_myu5CoUFndBkJ5sZFCiSoi-rM6UY-x-Wog6C7nl_6pgXt9M0Z-YPfVCHSvIYS5PlyRidhE=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 18700000 - displayName: JULIA GISELLA uniqueId: '@juliagisella' channelId: UCCPsBYxLUykj5xbgOGTRzKQ avatarUrl: >- https://yt3.googleusercontent.com/2n0OZs6fyMF6lvszolH4Pe5s-4koRhrWR7R2julWoeKwnAsLgUTS_6COm0CnGzuf5vIhLvepsNw=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 18100000 - displayName: Jennifer Lopez uniqueId: '@jenniferlopez' channelId: UCr8RjWUQ_9KYcIPmWiqBroQ avatarUrl: >- https://yt3.googleusercontent.com/u0IEPhk-hqU3pbeBNAPf5EQRwQs2mnT1-3rRQaGt3pXhf6lhQgFk3j6LQfupRNV0iYIU4BeIQJw=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 17500000 - displayName: Vogue uniqueId: '@vogue' channelId: UCRXiA3h1no_PFkb1JCP0yMA avatarUrl: >- https://yt3.googleusercontent.com/pjWEB6VpO5GmzI7aGg6pAjkNSdLf75LKoUXmmj2HAs1Fq1V1zlcevvR4hf7J9VtV7fYxaYJHS8g=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 16200000 - displayName: MrBeast uniqueId: '@mrbeast' channelId: UCX6OQ3DkcsbYNE6H8uQQuVA avatarUrl: >- https://yt3.googleusercontent.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 473000000 - displayName: Alan's Universe uniqueId: '@alanchikinchow' channelId: UC5gxP-2QqIh_09djvlm9Xcg avatarUrl: >- https://yt3.googleusercontent.com/QYrADJNN_BMJSYm0LkqAs13ehWHjtxITE7kSBPsEIB_I_VFeDvujpH4aJfHfJO3FsFMsYa6Oig=s900-c-k-c0x00ffffff-no-rj totalSubscribers: 100000000 platform: youtube traceId: 6ddf6c22a7a84b83e9a98f70a06e6235 timestamp: 1774586488186 creditsAvailable: 2627.89 creditsUsed: 3.04 errorCode: '' errorDescription: '' success: true '400': description: Validation error. content: application/json: schema: type: object title: ValidationErrorResponse properties: success: const: false error: type: string message: type: string timestamp: type: integer required: - success - error - message - timestamp examples: missing description: summary: Missing description field value: success: false error: VALIDATION_ERROR message: 'Missing required field: ''description''.' timestamp: 1770099403116 description too long: summary: Description exceeds 1000 characters value: success: false error: VALIDATION_ERROR message: >- The 'description' field must be between 1 and 1000 characters. timestamp: 1770099403116 '429': description: Exceeded quota or rate limit. content: application/json: schema: type: object title: QuotaErrorResponse properties: success: const: false error: type: string message: type: string remainingPlanCredit: type: number required: - success - error - message - remainingPlanCredit examples: rate limit: summary: Rate limit exceeded value: success: false error: RATE_LIMIT_EXCEEDED message: Too many requests. Please try again later. quota exceeded: summary: Credit quota exceeded value: success: false error: QUOTA_EXCEEDED message: Not enough credits to complete this request. security: - ApiKeyAuth: [] servers: - url: https://apiv3.creatordb.app description: Production Environment (CreatorDB Headless API V3) x-codeSamples: - lang: bash label: cURL source: | curl -X POST "https://apiv3.creatordb.app/nls" \ -H "Content-Type: application/json" \ -H "api-key: " \ -d '{ "description": "Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers" }' - lang: python label: Python source: > import requests url = "https://apiv3.creatordb.app/nls" payload = { "description": "Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers" } headers = { "api-key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, stream=True) for line in response.iter_lines(decode_unicode=True): print(line) components: securitySchemes: ApiKeyAuth: type: apiKey description: The valid CreatorDB API key for authentication. name: api-key in: header ````