---
title: "Search creators"
method: POST
path: "/api/v2/creator-search/search"
tags: ["Creator"]
---

# Search creators

`POST /api/v2/creator-search/search`

## Request

- Base URL: `https://api.instantly.ai`
- URL: `https://api.instantly.ai/api/v2/creator-search/search`
- Auth: HTTP bearer

Finds creators by platform, niche, audience and location (`kind: structured`), from a sentence (`ai_text`), or like given creators (`lookalike`). The first 20 result pages a day are free; after them a page costs 0.1 credits per result for a filter search and 0.25 for the other kinds (see `GET /creator-search/search-allowance`). Set `max_credits` to get a 402 with the price instead of a charge. A paid page is charged once per `idempotency_key`. Creator search is rate limited: a busy second answers 429 with `Retry-After`. `platform: all` and sorting by followers or engagement need several lookups per page, so they meet that limit more often; retry after `Retry-After`.


Requires one of the following scopes: `supersearch_enrichments:create`, `supersearch_enrichments:all`, `all:create`, `all:all`

## Request body

- object
  - `platform` 'all' | 'instagram' | 'tiktok' | 'youtube', required
  - `kind` 'structured' | 'ai_text' | 'lookalike' | 'result_image', required
  - `sort` 'relevance' | 'followers' | 'engagement'
  - `page` integer
  - `page_size` integer
  - `query` string
  - `filters` object
    - `creator` string
    - `locations` union[]
      - union
        - string
        - number
    - `languages` string[]
    - `followers` object
      - `min` number
      - `max` number
    - `engagement_rate` object
      - `min` number
      - `max` number
    - `average_views` object
      - `min` number
      - `max` number
    - `growth_rate` object
      - `min` number
      - `max` number
    - `posting_frequency` object
      - `min` number
      - `max` number
    - `last_posted_days` integer
    - `interests` union[]
      - union
        - string
        - number
    - `hashtags` string[]
    - `bio` string
    - `account_type` 'creator' | 'business' | 'regular'
    - `verified` boolean
    - `has_email` boolean
    - `authenticity_min` number
    - `brand_ids` union[]
      - union
        - string
        - number
    - `audience_locations` object[]
      - `id` union, required
        - string
        - number
      - `weight` number
    - `audience_languages` object[]
      - `id` union, required
        - string
        - number
      - `weight` number
    - `audience_interests` object[]
      - `id` union, required
        - string
        - number
      - `weight` number
  - `creator_refs` string[]
  - `visual_ref` string
  - `idempotency_key` string, uuid, required
  - `max_credits` integer
  - `exclude_saved` boolean
  - `proposal_candidate_id` string

## Response `200`

Default Response

- object
  - `items` object[], required
    - `creator_ref` string, required: Opaque reference to the creator in this workspace; pass it back to convert or find lookalikes. It expires after a while: search again for a fresh one.
    - `platform` 'instagram' | 'tiktok' | 'youtube', required
    - `name` string, required
    - `handle` string, required
    - `profile_url` string, nullable
    - `avatar_url` string, nullable
    - `bio` string, nullable
    - `location` string, nullable
    - `category` string, nullable
    - `followers` number, required
    - `engagement_rate` number, required: A fraction, 0 to 1
    - `average_views` number, nullable
    - `posting_frequency` number, nullable: Posts per month
    - `growth_rate` number, nullable
    - `has_email` boolean, required: Whether an email is known for this creator; converting one without an email charges nothing
    - `is_verified` boolean, nullable
    - `is_unlocked` boolean, required: Whether this workspace already bought the creator's insights
    - `collaboration_brands` string[], required
    - `content` object[], required: Recent posts
      - `id` string, required
      - `url` string
      - `thumbnail_url` string
      - `video_url` string
      - `media_type` 'image' | 'video' | 'carousel'
      - `visual_ref` string: Pass as `visual_ref` to find creators with similar posts
      - `caption` string
      - `hashtags` string[]
      - `published_at` string
      - `likes` number
      - `comments` number
      - `views` number
      - `shares` number
      - `is_sponsored` boolean
  - `total` number, required: How many creators match, as estimated by the search
  - `page` integer, required
  - `page_size` integer, required
  - `has_more` boolean, required
  - `terminal` boolean, required: True when no further page can be read for this search
  - `content_pending` boolean: True when the creators' recent posts are not part of this response
  - `credits_cost` number, required: Credits this page cost; 0 for a free or cached page
  - `free_pages_remaining` integer, nullable: Free result pages left today after this one; null when it could not be read
  - `filtered_out_count` integer
  - `excluded_count` integer: Creators left out because they are already on one of your creator lists (`exclude_saved`)

## Other responses

- `400`: The request is invalid (e.g. missing required fields, invalid field values, or an invalid state for the operation)
- `401`: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
- `402`: Default Response
- `403`: This request is forbidden (the API key scope or workspace plan does not allow this action)
- `404`: The requested resource was not found
- `429`: Creator search is busy; retry after the `Retry-After` header's seconds.

## Changes

- **2026-11-03** `c781051105a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/instantly/apis/api-explorer/changes/api/v2/creator-search/search/post.md)

---

[API](https://skmtc.dev/instantly/apis/api-explorer.md) - [All operations](https://skmtc.dev/instantly/apis/api-explorer/llms.txt) - [OpenAPI document](https://skmtc.dev/instantly/apis/api-explorer/revisions/3daaa5f6b0be?raw)