Changelog

Dated, developer-facing changes to the public API and SDKs — new endpoints, new events, changed costs, releases. This is distinct from our internal engineering changelog.

1. changed2026-11-07v1

   Goody-bag follow lists are read every 7 days and say when one cannot be read

   Follow lists are read again every 7 days instead of every 6 hours; send a handle to POST /v1/goodybag/follow-sources again to read it sooner. A list you hold that TikTok stops showing now says so on GET /v1/goodybag/follow-sources: status hidden (a private account or a hidden following list) or not_found (no account under this handle). Neither is scanned, both show accountsRead 0, and each is read again at the next refresh. If the account changed its handle, the list moves to the new handle. GET /v1/creators/:uid/following and /followers answer isPrivate: true with no entries for a private account, and ask TikTok again once the answer is past the list's freshness window.

2. fixed2026-11-02v1

   Comments we cannot read are a 503, not a not-found

   GET /v1/videos/:videoId/comments answered 404 video_not_found for a real video whose comments we had never collected. It now answers 503 comments_unavailable (free, retryable: false) when we have never collected the video's comments and cannot collect them right now; repeating the same request will not change the answer until comments can be collected again. GET /v1/videos/:videoId still tells you whether we hold the video, and comments we already hold are served as before.

3. changed2026-11-02v1

   Realtime is sold by LIVE rooms held at once and spends no credits

   The realtime stream at /v1/live/stream no longer spends credits, however long you stay connected. Your plan sets how many LIVE rooms the workspace can hold at once: 1 on Free, 150 on Starter, 600 on Pro, 1,500 on Scale, 3,000 on Agency. Read limits.wsConcurrencyCap from GET /v1/entitlements for your workspace's number. The monthly minute figure in the same limits is deprecated: it now equals wsConcurrencyCap × 43,200 (every room open all month, so no ceiling), nothing enforces it, and it will be removed in a later release.

4. fixed2026-11-02v1

   Follow lists and comments: a TikTok failure is never a not-found

   When a request to TikTok fails while we read a creator's followers or following, or a video's comments, and we do not hold the page you asked for, the read answers 202 "collecting" with a Retry-After header (free) instead of a 404. Poll the same URL after Retry-After. Lists and comments we already hold are served as before, and a creator or video TikTok says does not exist still answers 404. A rare failure on our side while GET /v1/creators/:uid checks who used to hold a username now answers 503 creator_lookup_unavailable (retryable, free) instead of 404.

5. changed2026-11-02v1

   One charge per TikTok fetch

   When several requests need the same creator while it is being fetched from TikTok, the first request that receives the result pays the profile price (1,250 credits) and every other one pays a stored read (1 credit); before, each of them paid 1,250. Follower and following lists (4,000 credits) and video comments (500 credits) work the same way: one fetch from TikTok is charged once, to the read that delivers it. A 202 "not ready yet" answer stays free, and so does an older copy served while the fetch runs (that copy is a stored read, 1 credit). The next read that delivers the fetched data pays the fetch's price if no other read has paid for that fetch, and only within 10 minutes of the fetch finishing; otherwise it is a stored read. A fetch nobody comes back for is not charged.

6. changed2026-11-02v1

   Stories priced like the profile read

   GET /v1/creators/:uid/stories now costs 1,250 credits when it has to fetch the creator from TikTok first, and 1 credit when the creator is already stored (before, it was always 1 credit). The story tray itself is included. A 202 or a 404 is not charged, and a stories read and a profile read that share one fetch from TikTok pay for it once.

7. changed2026-11-02v1

   A bare number is a user id first

   On GET /v1/creators/:uid and its /stories, /videos, /changes, /analysis, /followers and /following reads, a :uid made only of digits is now read as that creator's TikTok user id first, then as a username made of those digits. Before, the username came first, so a number could open a different account whose username is that number. A creator found by its user id is refreshed from its own account, never by searching the number as a username. Write @123456 or the profile URL to mean the username; /videos, /changes and /analysis now accept those spellings too (they answered 404 before).

8. fixed2026-11-02v1

   A TikTok failure is never answered as not found

   When the request to TikTok errors or is rate-limited while we fetch a creator we have not stored yet, GET /v1/creators/:uid and /stories answer 202 with a Retry-After header (not charged) instead of a 404, a blank record, or the account that used to hold that username. Poll the same URL after the wait. A creator we already hold a full profile for is served from what we hold (1 credit). @alice and the profile URL of a creator we already hold now read it exactly like alice: a stored read (1 credit) while it is up to date, where they used to cost 1,250.

9. fixed2026-11-02v1

   A username TikTok says nobody holds answers 404

   A creator we only knew from rankings or LIVE lists, never fully fetched, now answers 404 creator_not_found (retryable: false, not charged) on GET /v1/creators/:uid and /stories when you ask for it by a username TikTok says nobody holds. Before, it answered a thin 200 charged 1 credit. Asking for it by its numeric user id still returns what we hold.

10. fixed2026-11-02v1

    Region from the right account

    A creator's region is no longer taken from another account that used to have the same username. It now comes only from data about that same account (its user id), and is null when we have none.

11. added2026-11-01v1

    Team battles: linkMicArmies.teamArmies and battleType

    2v2, 1v3 and free-for-all battles now carry their points in linkMicArmies.teamArmies: one entry per team with teamId, the team's points and each host's userId and points. linkMicArmies and linkMicBattle also carry battleType (1 = 1v1, 2 = 2v2, 3 = free-for-all, 4 = 1v3; 0 when absent), linkMicBattle carries battleId, startMs and durationSec, and linkMicArmies carries battleId. Read teamArmies whenever it is non-empty and ignore teams: a 2v2 often still sends teams, but each side holds a whole team's total. 1v1 scoreboards keep using teams. Additive; no existing field changed.

12. fixed2026-11-01v1

    Docs: counting gifts sent as a batch

    A batch send of N gifts arrives as N gift events that share one logId, and each carries the whole batch in fanTicketCount, so summing fanTicketCount over every event counts a batch N times. The gift docs now say to count a send once, on the event where isCompleted is true: diamondCount × repeatCount. On the batches measured (one-shot gifts), every copy is complete on its own event. The events themselves did not change.

13. fixed2026-11-01v1

    Fixed: a 202 "not ready yet" answer is never billed

    When a read answers 202 because its data is still being fetched — the creator profile, stories, following, followers, video comments and LIVE playback, by GET or HEAD — no credits are charged. Poll the same URL: the request that answers 200 is billed as usual. Requests that start a job are still billed when the job is accepted: POST /v1/live/creators/:uid/refresh (202) and POST /v1/exports (201).

14. added2026-10-24v1

    New: Goody-bag feed — watch sets, a capacity read and a goodybag.* WebSocket plane

    Choose the LIVE rooms to watch (the best-ranked N, or creators you name) and receive each goody bag once, the moment it appears, on the realtime socket. PUT/GET/DELETE /v1/goodybag/watch-set and GET /v1/goodybag/capacity under the new goodybag:manage scope; the feed is goodybag.subscribe → goodybag.status / goodybag.event on the existing socket under the new goodybag:read scope, carried in the handshake token only while your workspace's grant is in force. A granted capability (contact us); not credit-metered. See the Goody-bag feed guide.

15. removed2026-09-24v1

    Removed: LIVE session list + detail, the live_sessions export — SDKs sdk-js 0.3.0 / toktik 0.2.0

    GET /v1/live/sessions and GET /v1/live/sessions/:id now answer 410 endpoint_removed (never billed); the live_sessions export dataset and the playground's liveSessions operation are gone. Per-creator LIVE history stays at GET /v1/live/creators/:uid/performance. This is an exception to the /v2 rule below: the endpoints had no external traffic. @toktikhq/sdk-js 0.3.0 and toktik 0.2.0 drop the session methods and take the full export request in exports.create.

16. changed2026-09-24v1

    Exports carry revenue and earnings; Whale intel depth by plan; new creator_gifters export

    Every export adds est_revenue_usd / est_earnings_usd (estimates from diamonds; blank on Shopping boards, which score in points); gifters exports take region + segment; creator_roster adds identity, boards and gifts received 24h/7d/30d. GET /v1/creators/:handle/gifters (+ /live) returns Free the top 3 gifters, Starter the top 3, Pro+ all, with totals from Starter up and an access object describing the cap. New export dataset creator_gifters. GET /v1/watchlist adds giftTotals, gifterSummary.windows and giftTotalsAccess. Rankings/gifters exports require the Live module (403 module_not_entitled).

17. added2026-08-04v1

    New endpoints: Creator Stories, Watchlist API, LIVE playback, creator search, alert-rule editing

    GET /v1/creators/:uid/stories (content:read) returns a creator's active story tray. The workspace Watchlist is now an API: GET/POST/DELETE /v1/watchlist under the new watchlist:manage scope (not credit-metered). GET /v1/creators (creator:read) searches the observed creator set, and GET /v1/live/creators/:uid/playback (live:stream) returns HLS/FLV sources for a live room. Alert rules gained PATCH, DELETE and a test-fire POST. Every response now carries a full typed schema in the OpenAPI reference.

18. added2026-07-24v1

    Developer docs: Realtime guide, SDK pages, versioning, changelog & status

    Full Realtime guide with the complete event-type reference (10 events, no more), SDK docs for both clients with runnable samples, plus this versioning policy, public changelog and live status page.

19. added2026-07-24v1

    Python SDK — toktik 0.1.0

    Official Python client: dependency-free REST plus an asyncio realtime LIVE-event client. Feature parity with @toktikhq/sdk-js.

20. added2026-07-23v1

    JavaScript SDK — @toktikhq/sdk-js 0.2.0

    Namespaced typed client (rankings, live, creators, content, gifters, trends, exports, account) plus the realtime stream client.

21. added2026-07-23v1

    Realtime LIVE event WebSocket

    Any-creator realtime stream at /v1/live/stream with a REST-minted handshake token, and honest queued/active/offline statuses.

22. added2026-07-22v1

    Public /v1 data-plane + OpenAPI contract

    Bearer-key REST surface across rankings, live, gifters, creators, content and trends, served with a live GET /openapi.json.