Recording and coverage

What Elixir captures, how often, and why an answer is never a live scrape.

The official Clash Royale API answers only "what is true right now": a profile, a clan roster, and a battle log of roughly the last 30 battles (most commonly exactly 30). Elixir MCP records those observations continuously and keeps them. This page is what that promise means precisely.

The game's own "last seen"

Clash Royale reports lastSeen for each member inside a clan's member list only — a player's own endpoint does not carry it. Elixir MCP captures it on every clan roster poll and serves it as last_seen_in_game on players_profile and on each clans_roster member.

Three things worth knowing:

• It is when the player was last active, not when this service last looked, and not last_recorded_battle — which only moves when a battle was captured. A member who opens the game daily without battling is indistinguishable from a departed one without it.
• It is the predicate the game uses to seed a river race roster. Members last seen before a race began are absent from that race's participants entirely, whether or not they battle and whether or not they joined in time. That is why war_current.members_not_in_race and this field belong together.
• It cannot be backfilled, and it is only obtainable while a player is in a clan being polled. Null means no polled roster has carried them yet.

Added means recorded

There is no watch step and no approval queue. Tracked means recorded: tracking a subject on your account is the request to record it, and capture starts at the next scheduler tick. (Before contract 1.0.0 the tools said "add"; the act is the same.)

Slots are the only gate; see Limits.

One recording, many reasons

Every subject has at most one active recording, shared by everyone who wants it. The recorder counts the reasons a subject is wanted and starts, widens, or stops the recording accordingly:

The widest reason wins. Removing your own reason frees your slot; the recording stops only when no reason remains anywhere. A clan's scope settles up or down to the widest remaining reason; a player's scope only ever widens. History is never deleted when a recording stops.

Scope: what is actually polled

Put plainly: activity follows the clan itself — its roster, its members arriving and leaving, and its river races. Comprehensive also records every member's battles, which is what builds the clan a full history rather than a record of who was in it.

Every tier has one activity clan slot, and it is meant for your own clan: it is what approval spends when your access request is granted, so the clan you play in is being followed from your first sign-in. Comprehensive is the upgrade, and it costs proportionally more to run — the member tier has none, so elixir_track_clan, which defaults to comprehensive, needs scope: "activity" there.

Players you track are always comprehensive. A recorded player's current clan is also read for roster and membership tracking — a few times a day, following the clan's own liveliness — without a slot and without polling the other members.

A roster poll records what it carries (since 2026-09-17). Every clan the recorder reads gets one row per game day of its own numbers (clan score, war trophies, member count, required trophies, weekly donations), and every member on that roster gets a row in the same daily series a recorded player's profile writes — trophies, donations, clan rank, arena and the game's own last-seen — whether or not their profile is recorded. The two writers share the row: a member with a recorded profile has the profile's lifetime counters on it too, and each half is dated by its own observation. The profile's progress buckets (the seasonal Trophy Road, 2v2 League, Merge Tactics) are kept as a series of their own; a bucket the player has not touched this season writes nothing. The readers over these series arrive with the next contract bump; today players_timeline already returns the roster-written days.

Relationships, primary, nicknames

Each player you track is your primary (exactly one: the first you track, or whichever you mark relationship: "primary"), an alt, a friend, or someone you are watching (the default). The primary is what "omit player_tag" means on your connection. Claims are taken at your word (claim_status: unverified); several accounts may track the same player and share the recording.

elixir_nickname({ player_tag, nickname }) stores a private label (1 to 40 characters, null clears) that only your account and your agents see; players_search ranks your nicknames first. It is the one write the website's Explore page performs.

Collections

A collection is a curated, named group (slug ^[a-z0-9][a-z0-9-]{1,38}$, public or private, player or clan kind) that records its members: adding a tag to a collection is a recording reason like any other, at the collection's scope (comprehensive by default). collections_edit takes add, remove or set with up to 500 tags per call and refuses the whole call on one malformed tag. Collections are a family-tier feature; reading public ones needs only cr:read.

Leaderboards

The CR API shows a ranking as it is this minute and forgets it. The recorder keeps it: the global Path of Legends board and every location the API lists — 262 countries and regions — once a day, in the first planning tick after 10:00Z, the hour the season rolls, so a season's last daily snapshot is the board as it stood going into the roll. Each fetch that differs from the last becomes a snapshot with a row per placed player (rank, rating, name, clan); an identical later fetch confirms the existing snapshot rather than duplicating it, so the record also says how long a board held.

rankings_players reads a board — the latest, or as it was at any earlier instant with as_of — paged, because a whole board can run to a thousand places. rankings_clans aggregates it: which clans have the most rated players, ties broken by the clan's best-placed player. Both count over everyone above the rating floor, not a top-100 slice; a Path of Legends board lists only players above that floor, and a season resets everyone below it, so a board is small in a season's first days and fills through the month. live: true on either asks for a read of the board no older than a minute: served if in hand, otherwise queued while the latest snapshot answers with live_status.state: "pending".

Everything else the API forgets about a season is recorded beside it. A season's final Path of Legends board — the settled standing at full depth, 9,999 places — is fetched once the day after it rolls and was backfilled for every season since October 2022, the ranked ladder's first; read it with board: pol_final and a season, either the number game_clock counts (135 for August 2026) or the API's own name for the season, the month it started in (2026-08). The Pass's in-game "Season 87" is a third numbering the API does not use anywhere. The clan ladders (clans by clan score, clanwars by clan war trophies, 1,000 places by location) are recorded daily for global, the United States and Japan — rankings_clan_ladder. The game-mode leaderboards (Merge Tactics, Touchdown, 2v2 League and the rest) are enumerated from the API daily, so a board that rotates in is followed without anyone naming it. Call rankings_players({ board: "mode", location: "list" }) for the recorded ids, names and enabled state, then read board: "mode" with a returned location. The catalog is a recorded read; omit live and as_of when listing it. A mode board or badge is not evidence that its battles appear in the API's battle log; missing recorded battles do not prove absence. What was on — the events the API listed as running, with no dates — is recorded daily as sightings, so game_events is the season's calendar built from the days each event was seen. rankings_timeline reads any of the player boards across a window: a player's rank and rating at every snapshot, a clan's rated players and best rank, or the board's own floor, summit and field size — the season story at daily resolution.

A top-200 appearance on the global board is a recording reason. Any player who reaches it is recorded at comprehensive scope — every battle, with the rank and rating each one carried — until the next season roll plus three days, however far they fall in between. That grace is deliberate: the board is empty for the first hours after a roll, and the only way the opening battles of the next season's #1 are captured is that they were recorded for being in last season's field. The Trophy Road boards are watched but have been served empty by the API for recent seasons.

How often a subject is fetched

Recording is a schedule over one shared, conservative API budget that the whole collector fleet stays inside. The rules below only ever shorten each other.

Subjects added together are de-phased by a stable per-subject offset so a batch does not poll in lockstep. A burst can still roll off the log between two polls; the Status page publishes how many of the last day's polls found that it had, and so does capture_audit_24h in /api/public/status.

Freshness, as the envelope reports it

Every response's meta says what it was built from:

Freshness advances only when a payload is admitted, never on a fetch that was refused, so a stale value is honest.

Daily series

Three tables hold the record's day-grained history, one row per subject per game day, the last observation of the day winning:

Two writers share a member's row. The roster writes trophies, donations, donations received, arena, the clan, the rank and the game's last-seen at its own cadence (every fifteen minutes for a tracked clan); the profile writes the lifetime block at its own (every eight hours or slower). Each writer's columns are dated by its own stamp (roster_observed_at, profile_observed_at), the shared columns belong to whichever observation is newer, and observed_at is the newest of either. So "trophies on day D" is the day's last read from either source; "wins on day D" is the day's last profile read, and a day the roster wrote with no profile poll carries the roster's columns and null elsewhere, with profile_observed_at null to say so.

source on a point is api for a row from a recorded payload (live or the archive backfill of 2026-09-17) and elixir-bot for the few rows imported from POAP KINGS' earlier bot on 2026-09-18: five member-only days before the first archived roster (2026-03-07 to 03-11, their instant the bot's usual roster hour) and the Sunday pre_reset rows for members whose profile was not recorded then. A window that contains such a point says so in notes[]. The July to September 2026 hole in the profile archive was filled by replaying the bot's own profile payloads; that replay wrote rows and never moments, so the timeline for those players is quiet over those weeks by rule, not by absence of play.

kind selects the daily row (the default), the pre_reset row (the hour before the Monday 00:10 UTC donation reset, the honest weekly donation total) or the season_roll row (the hour before the season rolls). A bucket of the progress series that reads zero trophies and zero best trophies is not a row: no record for no activity.

Completeness

elixir_coverage({ player_tag? }) returns:

Two caveats the numbers cannot escape: the lifetime counter includes some modes the battle log never shows, so a ratio under 1.0 is an upper bound on loss; and unmeasured_tail_hours is not part of the ratio. Missing coverage is unknown, not evidence of absence.

players_timeline adds snapshots_available_from, and a line in notes[], when you ask for dates before snapshots began.

Participation by week

clans_participation({ clan_tag?, weeks? }) answers, for every open member of a clan in one call, what they did week by week: the raw material for a clan's own participation rules, which Elixir does not have. It measures; it never rates.

Null is unknown, never zero, throughout: a week with no snapshot has donations: null, a war day nobody polled has decks_used_today: null, a member with no recorded battle has days_since_battle: null. Counts cover recorded battles only; elixir_coverage per tag says how complete a member's log is. weeks is 1 to 8 (default 5). The per-member values are columns rather than rows so a full clan over eight weeks fits the response cap; should it not, the result_too_large hint names weeks and verbosity: "compact".

Reading the game live

live: true is a request for a read of the game no older than the API's own cache: 60 seconds for players, battle logs and boards, 120 for clans and the river race. It is asynchronous. If such a read is in hand, the tool answers from it (live_status.state: "fresh"). If not, one priority fetch is queued for the next collector that checks in and the tool answers now from the record as it stands, with live_status: { state: "pending", retry_after_s } and a note saying so; call again after that and the fresh view is there. A subject with no record at all answers live_pending with the same retry_after_s. Nothing waits on a collector inside a call.

7 recorded tools take the flag: players_profile, battles_query, clans_roster, war_current, rankings_clan_ladder, rankings_clans, rankings_players. The player tools can read any tag; clans_roster and war_current can read any clan, recorded or not; the board tools name their board and location. battles_query polls a player's battle log for the "what did they just play" path. Prefer these; they are the live lane with the record's shape.

live_fetch({ path }) is the raw catch-all: one authenticated GET against the Clash Royale API through the live lane, recorded on the way back. It needs the payload itself, so it answers live_pending until one is in hand, then { path, live: true, live_status, data, meta }.

/players/{tag}/battlelog is refused with result_too_large before the lane is spent: a raw battle log cannot fit the 48,000-character delivery cap, so the fetch would cost a live call and deliver nothing; battles_query({ player_tag, live: true }) polls the log once and answers in the compact recorded shape. Anything else is bad_request. The response is { path, live: true, data, meta } with data the raw payload: card levels there are on the API's rarity-relative scale (a maxed legendary reads 8/8), while every recorded tool serves the in-game 1 to 16 scale; cards_catalog carries both maxima. live_unavailable is answered only when the lane is not configured or the fresh payload was refused at admission.

Live fetches are capped per day by tier (20 / 100 / 250 / 1,000; owner and admin unlimited) and an agent spends its owner's allowance. A queued fetch is charged once, when it is queued; a fresh read already in hand and the follow-up call that finds it are free. Every collector in the fleet picks up a queued live fetch first, so the worst-case wait is one check-in interval (15 seconds) plus the fetch. Leaderboard fetches also enrol the ranked tags into the corpus.