Semantic Search

How AI-powered search finds relevant creators

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.

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.

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 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, named for callers that want an explicit confidence signal
• match.low_confidence: true for results in the weak tail, so you can separate “weaker matches” instead of treating every result as strong
• 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: geography honesty flag (see below); 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
}

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

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

The public search API accepts only instagram in the platforms array. Omit the field to use that default:

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

Limit

limit sets the maximum number of results the search session 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 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 — 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.