Find anyone. Then read their story.

Real query params from the handler: query (required — a prefix match against entity names/ids, not a full-text search), entity_types (repeatable, defaults to all three), sort_by (relevance default; also velocity_1h, velocity_24h, momentum, views, followers), limit (default 20, max 100), offset, and an opaque cursor for pagination. A cursor wins when both are supplied. The API overfetches through the requested page for every selected type, applies a stable global cross-type sort, and only then slices the page, so page 2 no longer repeats page 1.

copycurl -s "https://api.metrix.ac/api/v1/search?query=cooking&limit=5" \
  -H "Authorization: Bearer $TM_API_KEY"

copy{
  "query": "cooking", "total": 15, "limit": 5, "offset": 0,
  "has_more": true, "next_cursor": "eyJvIjogNX0=", // ← pass this back as ?cursor= for page 2
  "results": [
    { "entity_type": "creator", "entity_id": "cooking10121",
      "display_name": "Cooking101", "match_score": 1.0,
      "metrics": { "views": null, "velocity_24h": null, "momentum": null }, // ← metrics are null until we've computed velocity for this entity
    },
    { "entity_type": "creator", "entity_id": "cookingbomb", "display_name": "cookingbomb", "match_score": 1.0 }
  ]
}

Matching is prefix-based on the entity's own id/name, not a fuzzy or full-text search — query=cooking above only matched creators whose handle starts with "cooking." metrics stay mostly null for search hits because most matched entities haven't had velocity computed yet; it's a name index first, a leaderboard second.

{entity_type} is one of hashtag, creator, sound, video. Results intentionally mix entity types — a hashtag's related list can include the creators and sounds that ride it, not just other hashtags. match_score is the raw co-occurrence strength (NPMI); metrics.momentum is the same number ×100, purely for display.

copycurl -s "https://api.metrix.ac/api/v1/related/hashtag/food?limit=4" \
  -H "Authorization: Bearer $TM_API_KEY"

copy{
  "query": "hashtag:food", "total": 4, "results": [
    { "entity_type": "creator", "entity_id": "tastebuds_nyc", "match_score": 0.726, // ← creators AND sounds mixed with hashtags here
      "metrics": { "momentum": 72.59 } },
    { "entity_type": "sound", "entity_id": "7273614838022178818", "match_score": 0.6646,
      "metrics": { "momentum": 66.46 } }
  ]
}

Aggregated from every video we've discovered for this creator: view/engagement totals, posting cadence, top sounds, top hashtags.

copycurl -s "https://api.metrix.ac/api/v1/creators/cookingwithshereen/profile" \
  -H "Authorization: Bearer $TM_API_KEY"

copy{
  "creator": {
    "creator_id": "cookingwithshereen", "nickname": "Shereen Pavlides", "verified": true,
    "follower_count": null, "follower_count_known": false, // ← see note below,
    "video_count": 26, "total_views": 38570026, "avg_views": 1483463,
    "engagement_rate": 0.0032,
    "posting_frequency": { "daily_avg": 1.86, "last_7d": 2, "last_30d": 26 },
    "top_sounds": [{ "sound_id": "6847961051430914050", "title": "Mambo No. 5", "usage_count": 2 }]
  },
  "top_hashtags": ["cookingwithshereen", "foodies", "italianfood", "chicken", "homemade", "recipe"]
}

follower_count_known flags whether TikTok actually included a follower count on the responses we captured — it strips that field from roughly 86% of unauthenticated API replies, so null here is the common case, not a data gap on our end. Trust follower_count_known: true before trusting a non-null follower_count.

days (default 30, 1–365) controls the lookback window. Points come from periodic re-crawls of the creator's profile, not every single video snapshot.

copycurl -s "https://api.metrix.ac/api/v1/creators/cookingwithshereen/history?days=30" \
  -H "Authorization: Bearer $TM_API_KEY"

copy{
  "creator_id": "cookingwithshereen",
  "points": []
}

Real, live-captured, and genuinely empty for this creator — she has no periodic profile re-crawl snapshots yet, only per-video discovery data (which the /videos and /profile endpoints below draw on instead). An unknown creator_id returns 404; a known creator with no snapshot history returns 200 with points: [] like this — the two cases look different, so check for the 404 rather than assuming an empty array means "not found."

Follower growth is computed on read from the same snapshot history as /history above (windows: 24h, 7d, 30d); views reuses the entity-velocity rows also used by the trending/niches pages. engagement is always null for now — that computation hasn't shipped yet.

copycurl -s "https://api.metrix.ac/api/v1/creators/cookingwithshereen/velocity" \
  -H "Authorization: Bearer $TM_API_KEY"

copy{
  "creator_id": "cookingwithshereen",
  "follower": { "24h": null, "7d": null, "30d": null },
  "views": null,
  "engagement": null,
  "data_through": null
}

All-null here follows directly from the empty /history above — no snapshot rows means no growth windows to compute. Pick a creator with an active velocity row (visible via size_tier on the niches/trending pages) to see populated numbers.

data_through is present in the live response above but not yet declared on this worktree's CreatorVelocityResponse schema (src/api/routes/creators.py:101-105 only declares creator_id/follower/views/engagement) — likely the deployed API is a step ahead of this branch. Documented as observed since it's what a real client actually receives; worth reconciling in code separately.

limit/offset for paging, sort (discovered_at default, also views, likes), min_views to filter out low performers.

copycurl -s "https://api.metrix.ac/api/v1/creators/cookingwithshereen/videos?limit=2" \
  -H "Authorization: Bearer $TM_API_KEY"

copy{
  "creator_id": "cookingwithshereen", "total": 27,
  "videos": [
    { "video_id": "7663193409607224589", "views": 123100, "likes": 9112, "shares": 529, "comments": 82,
      "sound_id": "7663193464833673998", "hashtags": ["cookingwithshereen", "foodies", "greenbeans"],
      "discovered_at": "2026-07-18T00:32:22Z", "source": "creator_profile",
      "relative_score": null, "is_overperforming": null }
  ]
}

relative_score/is_overperforming come back null when the creator has no row yet in the internal creators summary table this ratio is computed against — real for many creators found through discovery rather than a direct profile crawl.

Fast, unseeded similarity from shared hashtag usage. For a deeper, seeded version that also weighs velocity and niche affinity, see the Creator Recommendations page.

copycurl -s "https://api.metrix.ac/api/v1/creators/cookingwithshereen/similar?limit=3" \
  -H "Authorization: Bearer $TM_API_KEY"

copy{
  "creator_id": "cookingwithshereen", "total": 3,
  "results": [
    { "creator_id": "soflofoodies", "similarity_score": 0.1228, "shared_hashtag_count": 7,
      "shared_hashtags": ["baking", "chef", "food", "homemade", "italianfood"] },
    { "creator_id": "jacksdiningroom", "similarity_score": 0.0909, "shared_hashtag_count": 5,
      "shared_hashtags": ["cake", "food", "italianfood", "italy", "steak"] }
  ]
}

fit_score blends hashtag_coverage (60%, share of the niche's hashtags this creator has used) and calibrated seed_affinity (40%, how close their content sits to the niche's seed topics). sound_coverage remains in the response as 0.0 for compatibility but does not affect the score until a sound-coverage source exists. Results are sorted by fit_score, and the top result is flagged is_primary: true.

copycurl -s "https://api.metrix.ac/api/v1/creators/cookingwithshereen/niche-fit" \
  -H "Authorization: Bearer $TM_API_KEY"

copy{
  "creator_id": "cookingwithshereen", "primary_niche": "food_cooking",
  "results": [
    { "topic_id": "food_cooking", "fit_score": 0.4089, "hashtag_coverage": 0.0154,
      "sound_coverage": 0.0, "seed_affinity": 0.9991, "is_primary": true }, // ← correctly lands her in food_cooking,
    { "topic_id": "sg_food_miami", "fit_score": 0.04, "hashtag_coverage": 0.0667,
      "sound_coverage": 0.0, "seed_affinity": 0.0, "is_primary": false }
  ]
}

Covers every niche in our taxonomy, not just the ones visible to your account — treat low fit_score topics past the primary as noise, not additional matches.