INinstantly
Creator

Search creators

Changed on

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

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

Request body

platform'all' | 'instagram' | 'tiktok' | 'youtube' required
kind'structured' | 'ai_text' | 'lookalike' | 'result_image' required
sort'relevance' | 'followers' | 'engagement'
pageinteger
page_sizeinteger
querystring
creator_refsstring[]
visual_refstring
idempotency_keystring uuid required
max_creditsinteger
exclude_savedboolean
proposal_candidate_idstring

Response

Default Response

totalnumber required

How many creators match, as estimated by the search

pageinteger required
page_sizeinteger required
has_moreboolean required
terminalboolean required

True when no further page can be read for this search

content_pendingboolean

True when the creators' recent posts are not part of this response

credits_costnumber required

Credits this page cost; 0 for a free or cached page

free_pages_remaininginteger nullable

Free result pages left today after this one; null when it could not be read

filtered_out_countinteger
excluded_countinteger

Creators left out because they are already on one of your creator lists (exclude_saved)

Example response

{
  "items": [
    {
      "creator_ref": "eyJ2IjoxLCJwIjoiaW5zdGFncmFtIn0",
      "platform": "instagram",
      "name": "Jane Doe",
      "handle": "janedoe",
      "profile_url": "https://www.instagram.com/janedoe",
      "avatar_url": "https://example.com/avatar.jpg",
      "bio": "Travel and food",
      "location": "Austin, United States",
      "category": "Travel",
      "followers": 120000,
      "engagement_rate": 0.034,
      "average_views": 25000,
      "posting_frequency": 12,
      "growth_rate": 0.02,
      "has_email": true,
      "collaboration_brands": [
        "Nike"
      ]
    }
  ],
  "page_size": 20
}

Changes