> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creator Discovery

> Find TikTok, Instagram and YouTube creators in your app's niche whose short videos reach far past their follower count.

**Creator Discovery** finds real short-form creators for your app's UGC campaigns. You describe the videos you want. Appeeky searches TikTok, Instagram Reels and YouTube Shorts, drops creators outside your app's niche, analyzes each creator's recent posts and ranks the small accounts whose videos travel furthest.

> [!NOTE]
>
> Requires a signed-in Appeeky account with a prepaid balance. Each analyzed creator costs **\$0.01**; searches are free. Top up in **Settings → Billing**.

***

## How it works

```
queries + app  →  search TikTok / Instagram / YouTube  →  group videos by creator
                                                                │
                              niche filter (drops creators outside your app's audience)
                                                                │
              analyze each creator's ~30 recent posts  →  score and rank  →  results
```

1. **Search.** Each query runs on each platform you pick: up to 5 queries and 3 platforms.
2. **Niche filter.** When you pass an app, its title, subtitle, category and description are used to judge whether each creator's videos reach the same audience. Creators who clearly don't fit are skipped before you pay for them.
3. **Analysis.** For each remaining creator, Appeeky pulls their recent posts and computes the metrics below. Analysis is spread across platforms, so a 3-platform search doesn't return TikTok only.
4. **Ranking.** Creators are sorted by score, best first.

A run takes 1–3 minutes. In the dashboard it lives under **UGC → Discover**.

***

## Metrics

| Field | Meaning |
| - | - |
| `score` | 0–100. Higher means a smaller creator with outsized, repeatable reach |
| `medianViews` | Median views over the analyzed posts |
| `viewsPerFollower` | Median views ÷ followers. Above `1` means videos travel past the follower base |
| `engagementRate` | Median (likes + comments) ÷ views |
| `outlierCount` | Breakout videos: posts with at least 3× the creator's median views |
| `postsPerWeek` | Posting cadence over the analyzed window |
| `nicheFit` | 0–1 fit with your app's audience; `null` when no app was given |

> [!NOTE]
>
> YouTube's Shorts listing has no likes or publish dates, so `engagementRate` and `postsPerWeek` are `null` for YouTube creators.

***

## Billing

* You pay \*\*$0.01 per creator analyzed**, from your prepaid balance. `maxCreators` caps the cost of a run: 20 creators cost at most $0.20.
* Searching and the niche filter are free.
* A creator is charged right before their posts are fetched. If the fetch fails, or the creator doesn't make it into the results, the charge is refunded automatically.
* If a run fails, every charge on it is refunded.
* When your balance runs out mid-run, the run completes with the creators already analyzed and says so in `error`.
* You can have at most 2 searches running at once.

Charges show in **Settings → Billing** as *Creator discovery*.

***

## API

| Method | Endpoint | Description |
| - | - | - |
| POST | `/v1/creators/discover` | Start a run (returns immediately) |
| GET | `/v1/creators/discover/:runId` | Run status and ranked creators |
| GET | `/v1/creators/discover` | Recent runs without results (`?limit=`, max 100) |

These endpoints use 0 API credits; analyzed creators are paid from your balance.

### Start a run

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/creators/discover \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["habit tracker", "morning routine"],
    "platforms": ["tiktok", "instagram", "youtube"],
    "maxCreators": 20,
    "app": { "platform": "apple", "storeAppId": "123456789", "country": "us" }
  }'
```

| Field | Type | Description |
| - | - | - |
| `queries` | string\[] | Up to 5 searches describing the videos. Optional when `app` is set: the app's subtitle and category are used |
| `platforms` | string\[] | Any of `tiktok`, `instagram`, `youtube`. Default: all three |
| `maxCreators` | number | Creators to analyze, 1–50. Default `20` |
| `app` | object | Optional. `platform` (`apple` or `google`), `storeAppId`, `country` (default `us`). Turns on the niche filter |

Response (`201`):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "id": "6f1c2a7e-6c5b-4f41-9a55-2d0b8f3f6b10",
    "status": "queued",
    "queries": ["habit tracker", "morning routine"],
    "platforms": ["tiktok", "instagram", "youtube"],
    "maxCreators": 20,
    "results": []
  }
}
```

### Poll for results

`GET /v1/creators/discover/:runId` returns `status`, which is one of `queued`, `running`, `completed` or `failed`. Poll every 5–10 seconds until it is `completed` or `failed`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "id": "6f1c2a7e-6c5b-4f41-9a55-2d0b8f3f6b10",
    "status": "completed",
    "videosFound": 61,
    "creatorsFound": 58,
    "creatorsAnalyzed": 20,
    "chargedUsd": 0.2,
    "error": null,
    "results": [
      {
        "profile": {
          "platform": "tiktok",
          "handle": "example.creator",
          "displayName": "Example Creator",
          "followers": 1051,
          "profileUrl": "https://www.tiktok.com/@example.creator",
          "verified": false
        },
        "metrics": {
          "postsAnalyzed": 30,
          "medianViews": 163703,
          "viewsPerFollower": 155.8,
          "engagementRate": 0.02,
          "outlierCount": 3,
          "postsPerWeek": 10.6,
          "score": 77
        },
        "nicheFit": 0.955,
        "topVideos": [
          { "url": "https://www.tiktok.com/@example.creator/video/…", "views": 2400000, "thumbnailUrl": "…" }
        ],
        "matchedVideos": []
      }
    ]
  }
}
```

`topVideos` are the creator's best recent posts by views. `matchedVideos` are the search hits that surfaced the creator.

> [!WARNING]
>
> Thumbnail and avatar URLs come from the platforms' CDNs and expire after a few hours. Store the post `url`, not the image URL.

### Errors

| Status | Code | When |
| - | - | - |
| 400 | `VALIDATION_ERROR` | No queries and no app, or invalid fields |
| 402 | `INSUFFICIENT_BALANCE` | Balance can't pay for one creator |
| 429 | `TOO_MANY_RUNS` | Two searches are already running |
| 503 | `NOT_CONFIGURED` | Creator discovery is unavailable |

***

## MCP

| Tool | Description |
| - | - |
| `discover_creators` | Start a run (`queries`, `platforms`, `max_creators`, `app_id`, `app_platform`, `country`) |
| `get_creator_discovery` | Poll a run; pass `include_videos: true` for top and matched videos |
| `list_creator_discoveries` | Recent runs, newest first |

Example prompt: *"Find 20 TikTok and Instagram creators for my habit tracker app 123456789 and tell me which 5 to contact first."*

***

## Tips

* Use queries that name what the videos are about, like "morning routine" or "budget tips", rather than your app's name.
* Start with `maxCreators: 10` to check the results before running a bigger search.
* Pass `app` whenever you can. The niche filter is what keeps loosely related creators out.


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