Ultra Search

Give Ultra Search a brief in plain words and get back a finished creator list. It reads the brief, searches our index, crawls TikTok for creators we don't have yet, and has a model judge every candidate against your brief. Each creator comes back with a tier, a fit score and a one-sentence reason.

What it does

• The same Ultra Search as in the app, with the same checks, the same pipeline and the same list. A search started here shows up in your account's Ultra Search history and in Lists.
• It runs in the background: from a few minutes to a few hours, depending on how much of the niche we need to crawl. You start it, poll its status, then read the list.
• The list keeps the judge's order, best first: bullseye creators, then adjacent, then craft, then near misses.
• Words like "ideally" or "bonus if" in the brief rank creators higher; they never filter anyone out. A number or a contact email is a hard requirement only when the brief says so ("at least", "must").

What it costs

Ultra Search uses no API credits. Each search you start uses one of your plan's monthly Ultra Searches, exactly as in the app, and the count is shared between the app, the API and the MCP server. How many you get depends on your plan; meta.quota always says. A search that stops on our side gives its Ultra Search back. Reading the status and the results is free.

Every response carries meta.quota so you can see what's left:

"quota": {
  "unlimited": false,
  "remaining": 14,
  "monthly_limit": 15,
  "bonus": 0,
  "period_end": "2026-11-05T00:00:00Z",
  "left": "14 of 15 left"
}

POST/v1/ultra_searches#

Starts a search. Your brief is read before anything is spent: if it names no topic, or asks for one specific account or link, you get a 422 with suggestions and nothing is used.

Body

curl -X POST "https://developers.tokfluence.com/v1/ultra_searches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "UK fitness creators who review sports drinks, ideally with 50k+ followers",
    "countries": ["GB"]
  }'

The answer is 201 with the same object the status endpoint returns, below.

GET/v1/ultra_searches/:id#

Where the search is. Poll it every minute or two until results_ready is true.

{
  "data": {
    "id": 4812,
    "brief": "UK fitness creators who review sports drinks, ideally with 50k+ followers",
    "stage": "judging",
    "stage_label": "Checking every creator against your brief",
    "started_at": "2026-10-22T09:14:03Z",
    "updated_at": "2026-10-22T09:31:40Z",
    "estimate_seconds_remaining": 420,
    "estimate_note": null,
    "reading": "UK fitness creators who review sports drinks, ideally 50k+ followers",
    "keywords": ["sports drink review", "gym supplements uk"],
    "countries": ["GB"],
    "counts": { "creators_found": 38, "bullseye": 11, "near_misses": 4, "below_floor": 6, "profiles_scanned": 912, ... },
    "country_split": { "confirmed": 30, "unconfirmed": 8, "countries": ["GB"] },
    "crawl": null,
    "list": { "id": 20931, "name": "Fitness creators in the UK", "url": "https://app.tokfluence.com/lists/20931" },
    "results_ready": true,
    "free_preview": false,
    "brief_reason": null,
    "brief_message": null,
    "brief_suggestions": [],
    "error": null
  },
  "meta": { "quota": { ... } }
}

GET/v1/ultra_searches/:id/results#

One page of the list, best first. Each creator uses the same schema as creators.search (tkc_ id, stats, contact emails), plus an ultra block with the judge's verdict.

Query

{
  "data": [
    {
      "id": "tkc_a1b2c3d4e5f6a7b8",
      "username": "liftwithjo",
      "follower_count": 84000,
      "region": "GB",
      ...,
      "ultra": {
        "rank": 1,
        "tier": "bullseye",
        "fit": 92,
        "reason": "Reviews protein and sports drinks from a Manchester gym, weekly.",
        "evidence": { "quote": "Honest protein reviews from my gym in Manchester",
                      "url": null },
        "audience_type": "consumers",
        "near_miss": false,
        "country_confirmed": true,
        "country_confidence": "confirmed",
        "country_signal": "profile_region",
        "platform": "tiktok"
      }
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 38, "final": true, "list_id": 20931,
            "age_filter": { "excluded_likely_minors": 0 } }
}

Creators whose own bio states an age under 18 are always left out, as on every search, and counted in meta.age_filter.

Errors

From an AI agent

The MCP server has the same thing as two tools. start_ultra_search asks first: its first call starts nothing and returns how many Ultra Searches you have left, so your assistant can check with you before using one. get_ultra_search reads the status and, once the list exists, a page of it. Over OAuth, starting a search needs the crawl permission.