Skip to main content

​
Semantic Search

Search understands intent, not just keywords. You describe the kind of creator you’re looking for and the API ranks results by relevance. Instead of matching exact words in bios or hashtags, it interprets the meaning behind your query and finds creators whose content, audience, and style align with what you need.

​
What Search Understands

Search works at two levels: factual knowledge and style and vibes.

​
Factual Knowledge

Influship indexes specific facts about creators — things they’ve done, places they’ve been, preferences they’ve expressed. You can search for concrete details and the engine matches against real data points from creator content and bios. Examples of factual queries:
  • went to Coachella
  • is a frequent flyer
  • likes Thai food and lives in LA
  • is going to college next year
  • has a golden retriever
  • recently moved to New York
These work because the engine has extracted and indexed specific facts from creator content, captions, and bios. If a creator posted about attending Coachella, a search for “went to Coachella” will find them.

​
Style and Vibes

Search also understands more subjective qualities — the overall feel of a creator’s content, their tone, and the kind of audience they attract. This is where it goes beyond a database lookup and into genuine semantic matching. Examples of style-based queries:
  • funny creators who don't take themselves too seriously
  • calm, aesthetic, minimalist content
  • raw and unfiltered — not polished or aspirational
  • educational but not boring
  • creators who feel like your friend, not a brand
You can combine both in a single query: fitness creators in LA who went to Coachella and have a funny, relatable style works because the engine handles factual and stylistic signals together.

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

​
Write Better Queries

Good queries usually include:
  • a niche or topic
  • an audience trait or outcome
  • optional platform context
  • optional content style or vibe
Examples:
  • fitness creators focused on home workouts
  • sustainable fashion creators with engaged audiences
  • educational skincare creators on Instagram
  • travel photographers who feel authentic and adventurous, not luxury or aspirational
  • tech reviewers who explain things simply — like they're talking to a friend
Weak queries are too vague to guide ranking:
  • influencer
  • someone popular
  • good creator
Queries can be up to 500 characters. That’s plenty for a detailed brief — use the space. The more specific you are about both facts and feel, the better the results.

​
What You Get Back

Each result includes:
  • creator: the canonical creator record
  • relevant_profile: the profile most relevant to the query
  • primary_profile: the creator’s main profile
  • match.score: a 0-1 relevance score
  • match.reasons: short explanations for why the creator matched
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,
        "reasons": [
          "Strong sustainable travel focus with eco-tourism content",
          "High engagement on destination and gear reviews",
          "Consistent brand-safe creator style"
        ]
      }
    }
  ],
  "search_id": "search_123",
  "total": 1,
  "has_more": false,
  "next_cursor": null
}

​
Read the Score Correctly

The score is a ranking signal, not a guarantee.
  • 0.90+ usually means a strong match
  • 0.75-0.89 is often usable
  • lower scores usually need tighter queries or harder filters
Use the reasons to understand why a creator ranked well before you trust the list.

​
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:
  1. match the semantic intent of sustainable fashion creators
  2. are on Instagram
  3. fall within the follower range you care about
  4. clear your engagement floor
  5. have a verified account

​
Available Filters

FilterTypeDescription
filters.followers.minintegerMinimum follower count
filters.followers.maxintegerMaximum follower count
filters.engagement_rate.minnumberMinimum engagement rate (0-100, percentage)
filters.engagement_rate.maxnumberMaximum engagement rate (0-100, percentage)
filters.verifiedbooleanOnly return verified accounts

​
Platforms

The platforms parameter controls which social platforms to search. It accepts an array of strings and defaults to ["instagram"]. Pass multiple platforms to broaden the search: 
{
  "query": "tech review creators",
  "platforms": ["instagram", "tiktok"],
  "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

Search uses a two-step model: create, then paginate. 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 for the session based on this limit. GET /v1/search/{id} paginates through the results using cursors. These requests are free — you’re just stepping through results you’ve already paid for. The key thing to understand: limit sets a ceiling, not a page size. If you create a session with limit: 25, that session will contain at most 25 results total. Pagination lets you retrieve them in smaller batches, but it doesn’t unlock additional results beyond the limit. For cursor mechanics and page size options, see the Pagination guide.

​
Implementation Advice

Search accepts natural language, but result quality depends on input quality. If your end users aren’t marketers or developers, consider using an LLM to clean up or refine their input before submitting it to the search endpoint. Test both approaches — sometimes raw user input works fine, sometimes a preprocessing step makes a real difference.
Use the API Reference for the current generated request and SDK examples. This page explains how search behaves; the reference is the source of truth for exact shapes.