Search Creators

Describe the creators you need and receive ranked Instagram matches with reasons and evidence.

Before you start	Details
Auth	API key or OAuth; supported payment protocols also accept keyless calls
Cost	25 credits plus 2 per delivered creator for API-key/OAuth calls
Limits	Query: 1–500 characters; result limit: 1–100, default 25
First run	Complete Quickstart or Search reference

Describe the content you need

Search matches details in creators’ content and bios, as well as their presentation style. Include the topic and format that matter to your campaign:

You need	Example query
A specific topic	`creators who teach clothing repair and sustainable fashion`
An interest or experience	`creators who discuss adopting a golden retriever`
A content format	`fitness creators with step-by-step home-workout tutorials`
A location and interest	`travel creators in the UK who cover rail journeys`
A presentation style	`skincare educators with calm, detailed ingredient explanations`

Review the returned reasons and evidence to see which content supports each match. Add concrete requirements as you refine the query; broad phrases such as good creator provide little direction.

Hard Filters

On top of the semantic matching, hard filters constrain results to creators who meet specific numeric or boolean requirements:

follower ranges
engagement rate floors
verification status
platform

Filters are applied after semantic ranking, so they narrow the pool without changing how relevance is scored.

Geography

When your query names a country (for example UK skincare creators or American fitness influencers), geography is treated as a hard requirement, not a preference. A creator whose verified location contradicts the requested country is excluded from results. A creator whose location can’t be verified is still returned, but flagged with location_unverified: true so you can tell an assumed match from a confirmed one. When your query names no country, location_unverified is null on every result.

What You Get Back

Each result includes:

creator: the creator’s identity and details
relevant_profile: the profile most relevant to the search query, or null when no profile data is available
primary_profile: the creator’s largest profile, or null when no profile data is available
match.score: a 0-1 relevance score
match.confidence: the same 0-1 relevance value as match.score
match.low_confidence: identifies lower-confidence results for additional review
match.reasons: short plain-text explanations for why the creator matched
match.evidence: the same reasons in structured form, each with a provenance label and, where the reason rests on a post, a source_post_id and a verbatim evidence_quote — see Match Reasons
location_unverified: true when the creator’s location could not be verified against the requested country; null when your query named no country

These fields can differ when the profile that best explains the match is not the creator’s largest profile. Example:

{
  "data": [
    {
      "creator": {
        "id": "c7a3e9d1-f5b2-4e8c-a6d0-3b9f1c7e5a2d",
        "name": "Jamie Torres"
      },
      "relevant_profile": {
        "platform": "instagram",
        "username": "jamietravels"
      },
      "primary_profile": {
        "platform": "instagram",
        "username": "jamietravels"
      },
      "match": {
        "score": 0.92,
        "confidence": 0.92,
        "low_confidence": false,
        "reasons": [
          "Strong sustainable travel focus with eco-tourism content",
          "High engagement on destination and gear reviews"
        ],
        "evidence": [
          {
            "text": "Strong sustainable travel focus with eco-tourism content",
            "provenance": "post_evidence",
            "fact_id": "b7c1f0a2-3d4e-5f60-8a9b-0c1d2e3f4a5b",
            "source_post_id": "23256c2e-51fa-4389-a4a1-945e461e951b",
            "evidence_quote": "Skipping the resort — here's how to travel this coast low-impact…"
          },
          {
            "text": "High engagement on destination and gear reviews",
            "provenance": "inferred",
            "fact_id": null,
            "source_post_id": null,
            "evidence_quote": null
          }
        ]
      },
      "location_unverified": null
    }
  ],
  "search_id": "123e4567-e89b-12d3-a456-426614174000",
  "total": 1,
  "has_more": false,
  "next_cursor": null
}

Search quality

Inspect quality.mode on the response and match.ranking_source on each result before displaying scores.

`quality.mode`	Meaning	UI guidance
`reranked`	All returned results received AI relevance scoring	Show relevance scores with their supporting reasons
`partially_reranked`	Some results received AI scoring and others use retrieval fallback	Check each result’s `match.ranking_source`; label fallback results separately
`retrieval_fallback`	Results use retrieval ranking	Label them as discovery candidates; do not present their scores as AI campaign fit

For example, a result with match.ranking_source: "retrieval_fallback" and match.score: 0.9 is a highly ranked retrieval candidate, not a 90% campaign-fit assessment. Review its evidence or use campaign match scoring before making a fit decision. quality.reason explains why fallback was used. Preserve this information when saving or displaying results. For older responses that omit quality and ranking_source, the contract defines the result as reranked. Scores are ranking signals rather than guarantees. Compare them alongside reasons and evidence; avoid applying one threshold across reranked and fallback results.

Combine Search with Filters

Use semantic search for discovery, then hard filters for boundaries.

curl -X POST https://api.influship.com/v1/search \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "sustainable fashion creators",
    "platforms": ["instagram"],
    "filters": {
      "followers": {
        "min": 10000,
        "max": 500000
      },
      "engagement_rate": {
        "min": 2.0
      },
      "verified": true
    },
    "limit": 25
  }'

That gives you creators who:

match the semantic intent of sustainable fashion creators
are on Instagram
fall within the follower range you care about
clear your engagement floor
have a verified account

Available Filters

Filter	Type	Description
`filters.followers.min`	integer	Minimum follower count
`filters.followers.max`	integer	Maximum follower count
`filters.engagement_rate.min`	number	Minimum engagement rate (0-100, percentage)
`filters.engagement_rate.max`	number	Maximum engagement rate (0-100, percentage)
`filters.verified`	boolean	Only return verified accounts

Platforms

Creator search uses Instagram. Set platforms to ["instagram"] or omit it to use the default:

{
  "query": "tech review creators",
  "platforms": ["instagram"],
  "limit": 10
}

Limit

limit sets the maximum number of results the can return. Range: 1-100, default: 25. This determines the billing cap for the session — start small (5-10) while prototyping and increase once you understand how your UI consumes results.

Search Pagination

The POST returns your search results together. Use GET to reopen those results in smaller pages. POST /v1/search creates a search session. You set a limit that caps the total number of results the session can ever return. You’re billed once based on the number of results delivered, up to that limit. GET /v1/search/{id} paginates through the results using cursors. These requests are free — they read the existing session results. For example, a session created with limit: 25 contains up to 25 results. Use GET to read that set in batches, or create a new search to discover more creators. For cursor mechanics and page size options, see the Pagination guide.

Search Feedback

Submit feedback for a search with the same account that created it. Feedback does not consume search credits.

curl -X POST https://api.influship.com/v1/search/SEARCH_ID/feedback \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "rating": "not_helpful",
    "reason": "wrong_location",
    "details": "I needed creators based in the UK."
  }'

Use helpful or not_helpful for rating. The reason and details are optional. Include the specific mismatch when reporting poor results, and avoid putting personal or confidential information in the details.

Refine searches in your application

Keep the original brief visible beside the results. If the reasons miss a requirement, refine that part of the brief before running another search. If you transform user input into a search query, compare the results with the original wording and preserve the requirements the user supplied.

See the API Reference for request fields, response schemas, and SDK examples.

Start building

Find and evaluate creators

Research and save

Apps and workflows

Live platform data

Connect your tools

Operate your integration

Describe the content you need

Hard Filters

Geography

What You Get Back

Search quality

Combine Search with Filters

Available Filters

Platforms

Limit

Search Feedback

Refine searches in your application

​Describe the content you need

​Hard Filters

​Geography

​What You Get Back

​Search quality

​Combine Search with Filters

​Available Filters

​Platforms

​Limit

​Search Pagination

​Search Feedback

​Refine searches in your application

Describe the content you need

Hard Filters

Geography

What You Get Back

Search quality

Combine Search with Filters

Available Filters

Platforms

Limit

Search Pagination

Search Feedback

Refine searches in your application