> ## 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.
## 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 for the platform you searched; falls back to `primary_profile` if no platform filter was set
* `primary_profile`: the creator's profile with the largest audience across all platforms
* `match.score`: a 0-1 relevance score
* `match.reasons`: short explanations for why the creator matched
When a creator is active on multiple platforms, these two fields can differ. For example, a creator might have 200K Instagram followers and 50K TikTok followers — if you searched with `platforms: ["tiktok"]`, `relevant_profile` is the TikTok account and `primary_profile` is the Instagram account.
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,
"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.
```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 `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:
```json theme={null}
{
"query": "tech review creators",
"platforms": ["instagram", "tiktok"],
"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 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](/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.