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

# Search Creators

> How AI-powered search finds relevant 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](/concepts/pricing) 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](/quickstart) or [Search reference](/api-reference/search/ai-powered-creator-search) |

## 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](/concepts/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:

```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
}
```

## 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](/concepts/match-reasons#campaign-match-reasons) 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.

```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

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

```json theme={null}
{
  "query": "tech review creators",
  "platforms": ["instagram"],
  "limit": 10
}
```

### Limit

`limit` sets the maximum number of results the <Tooltip tip="A search session is created by POST /v1/search. It holds a fixed set of results determined by the limit parameter.">search session</Tooltip> 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](/guides/pagination).

## Search Feedback

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

```bash theme={null}
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.

<Note>
  See the [API Reference](/api-reference) for request fields, response schemas, and SDK examples.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.