Deterministic · TikTok + Instagram
Trend Finder V1
Build a client-owned creator group, collect public videos and reels by actual publication time, and read separate deterministic winner lanes backed only by stored observations.
Production routes and schema are live as of 2026-08-01. TikTok operations are available. Instagram collection code is deployed, but active Instagram capacity is configured to zero until the operator canary is complete.
V1 contract, not Trend Detector V2
Trend Finder owns group configuration, publication-cutoff coverage, Trend-owned six-hour scheduling, and ranking by current views then real six-hour view rate. It does not invoke AI format fingerprints, OCR/frame/transcript analysis, format clusters, trend buckets, AI scores, or V2 cost gates.
Default lookback is seven days (accepted range 1–30). Collection is complete only when a connector crosses the inclusive create_time/taken_at cutoff or proves upstream exhaustion. Content exactly at the cutoff remains eligible and is not crossing proof; a strictly older item or exhaustion is required. A page cap, missing continuation, unproven ordering, rate limit, capacity stop, or transient error remains partial. Earlier committed pages survive a later-page failure.
Trend refresh is independent of Social API tier and refresh quota. A read never calls a provider or queues work.
Group and creator API
Body: name, optional lookback_days, and up to 100 {platform, handle} creators. Desired state commits before best-effort dispatch.
Creator identity is platform-qualified, so the same text handle on TikTok and Instagram is two memberships. Valid unknown handles are accepted as pending. Cross-client reads and mutations return 404 without cleanup or information leakage.
Separate winner lanes
Returns lanes.tiktok and lanes.instagram; at most 100 items per lane. No sort override or live pagination.
Each lane orders current_views DESC, views_per_hour_6h DESC NULLS LAST, then stable content ID. The baseline is the newest compatible observation at or before latest minus six hours; rate divides by actual elapsed hours. Instagram photos/carousels are excluded.
Every item includes publication/observation times, age, cadence, nullable baseline/span/rate, freshness, metric status, and rank. Coverage includes exact member-state counts, complete/partial truth, oldest due age, last success, and bounded stop/acquisition/refresh-error summaries.
Do not flatten operational truth
Creator states: pending, collecting, ready, partial, empty, error, unsupported. Winner metric states: ready, insufficient_history, stale, counter_reset, metric_unavailable. Freshness: fresh, stale, unavailable.
Missing metrics remain null, explicit zero remains zero, and a counter reset never becomes negative velocity. Failed/capacity-blocked work remains due and visible.
{
"error": "INVALID_REQUEST",
"message": "Request parameters are invalid.",
"request_id": "<REQUEST_ID>"
}Every error repeats that UUID in X-Request-ID. Provider, proxy, credential, SQL, and unbounded exception text are never returned.
Instagram capacity is an operator gate
A live route and automated fixture coverage do not prove live Instagram ordering, pinned-item behavior, continuation, or six-hour capacity. The required worker-equivalent provider canary remains open.
Production currently sets TRENDFINDER_MAX_ACTIVE_INSTAGRAM_CREATORS=0, so new Instagram demand returns 409 INSTAGRAM_CAPACITY_EXCEEDED. Before activating it, an operator must record the bounded canary and select an environment-specific ceiling. Missing/invalid configuration returns 503 INSTAGRAM_CAPACITY_UNCONFIGURED; zero is configured-but-disabled. See the operations runbook.