> ## Documentation Index > Fetch the complete documentation index at: https://docs.influship.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/concepts/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: ```json theme={null} { "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. ```bash theme={null} 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: ```json theme={null} { "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](/guides/pagination). ## 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](/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.