# getTournamentsList — API (TTournament) > Returns the list of tournaments currently visible to the user, scoped server-side to what the user's segments qualify them to see. > Import: `import { TTournament } from '@smartico/public-api'` > Search terms: getTournamentsList, tournaments, getTournaments, TTournament, TRibbon, TANGIBLE, POINTS_ADD, POINTS_DEDUCT, POINTS_RESET, MINI_GAME_ATTEMPT, BONUS, TournamentRegistrationTypeName, TournamentRegistrationStatusName, onUpdate, subscription, instance_id, tournament_id, name, description, image1, image2, image2_mobile, prize_pool_short ## Signature ```ts _smartico.api.getTournamentsList({ onUpdate }: { onUpdate?: (data: TTournament[]) => void } = {}): Promise ``` ## Parameters - `params` — Optional. Omit to fetch without subscribing. - `params.onUpdate` — Callback invoked with the full refreshed tournament list after every `registerInTournament` round-trip on this connection. Each call overwrites the prior callback. Never fires in visitor mode. ## Returns — `Promise` Array of `TTournament`. Each item: - `instance_id` (number) — ID of tournament instance. Generated every time when tournament based on specific template is scheduled for run - `tournament_id` (number) — ID of tournament template - `name` (string) — Name of the tournament, translated to the user language - `description` (string) — Description of the tournament, translated to the user language - `image1` (string) — 1st image URL representing the tournament, 544×216px - `image2` (string) — 2nd image URL representing the tournament, 920x200px - `image2_mobile` (string) — 2nd image URL representing the tournament for mobile, 720x400px - `prize_pool_short` (string) — The message indicating the prize pool of the tournament - `custom_price_text` (string) — The message indicating the price to register in the tournament - `segment_dont_match_message` (string) — The message that should be shown to the user when the user cannot register in tournament with error code TOURNAMENT_USER_DONT_MATCH_CONDITIONS - `custom_section_id` (number) — The ID of the custom section where the tournament is assigned The list of custom sections can be retrieved using _smartico.api.getCustomSections() method - `custom_data` (any) — The custom data of the tournament defined by operator. Can be a JSON object, string or number - `is_featured` (boolean) — The indicator if the tournament is 'Featured' - `ribbon` (TRibbon) — The ribbon of the tournament item. Can be 'sale', 'hot', 'new', 'vip' or URL to the image in case of custom ribbon, 250×300px - `priority` (number) — A number is used to order the tournaments, representing their priority in the list - `me` ({ /** The username of the participant */ public_username: string; /** The URL to the avatar of the participant */ avatar_url: string; /** The position of the participant in the tournament */ position: number; /** The scores of the participant in the tournament */ scores: number; /** The external user id of the participant */ user_ext_id: string; /** The crm brand id of the participant */ crm_brand_id: number; /** The user id of the participant */ user_id: number; }) — Info about current player in tournament - `prizes` ({ /** The name of the prize */ name: string; /** The description of the prize */ description: string; /** The image of the prize, 1:1 aspect ratio */ image_url: string; /** from-to range of the places to which this prize */ place_from: number; place_to: number; /** type of the prize: TANGIBLE, POINTS_ADD, POINTS_DEDUCT, POINTS_RESET, MINI_GAME_ATTEMPT, BONUS */ type: string; /** if the prize is points related, indicates amount of points */ points?: number; }[]) — Prize structure - `start_time` (number) — The time when tournament is going to start, epoch with milliseconds - `end_time` (number) — The time when tournament is going to finish, epoch with milliseconds - `registration_type` (TournamentRegistrationTypeName) — Type of registration in the tournament - `registration_count` (number) — Number of users registered in the tournament - `is_user_registered` (boolean) — flag indicating if current user is registered in the tournament - `players_min_count` (number) — Minimum number of participant for this tournament. If tournament doesnt have enough registrations, it will not start - `players_max_count` (number) — Maximum number of participant for this tournament. When reached, new users won't be able to register - `registration_status` (TournamentRegistrationStatusName) — Status of registration in the tournament for current user - `duration_ms` (number) — Tournament duration in millisecnnds - `registration_cost_points` (number) — Cost of registration in the tournament in gamification points - `registration_cost_gems` (number) — Cost of registration in the tournament in gems - `registration_cost_diamonds` (number) — Cost of registration in the tournament in diamonds - `is_active` (boolean) — Indicator if tournament instance is active, means in one of the statues - PUBLISHED, REGISTED, STARTED - `is_can_register` (boolean) — Indicator if user can register in this tournament instance, e.g tournament is active, max users is not reached, user is not registered yet - `is_cancelled` (boolean) — Indicator if tournament instance is cancelled (status CANCELLED) - `is_finished` (boolean) — Indicator if tournament instance is finished (status FINISHED, CANCELLED OR FINIALIZING) - `is_in_progress` (boolean) — Indicator if tournament instance is running (status STARTED) - `is_upcoming` (boolean) — Indicator if tournament instance is upcoming (status PUBLISHED or REGISTER) - `min_scores_win` (number) — The minimum amount of score points that the user should get in order to be qualified for the prize - `hide_leaderboard_min_scores` (boolean) — When enabled, users who don’t meet the minimum qualifying score will be hidden from the Leaderboard - `total_scores` (number) — Total scores across all participants in the tournament - `is_clan_based` (boolean) — True when this tournament groups participants by clan ## Behavioral contract **Subscription model (`onUpdate`)** The callback receives the FULL refreshed list (never a diff/patch). Each subsequent call to `getTournamentsList({ onUpdate })` REPLACES the prior callback — only one active subscriber at a time. Pass `onUpdate: undefined` (or omit it) to keep the prior callback in place; the callback is never auto-cleared. **Update triggers** — the callback fires when: 1. `registerInTournament(...)` resolves on this connection (any `err_code`). The refreshed list reflects the new `is_user_registered` / `registration_status` / `registration_count` on the affected tournament. Does NOT fire for: tournament lifecycle transitions (start, finish, cancellation), score updates, other users' registrations, or operator-side BO edits. Those changes surface only on the next cache miss (after the 30 s TTL) — poll manually if your UI needs sub-30s lifecycle freshness. **Server-side filtering** (what's excluded before the SDK sees it) The server filters by visibility segment and entry segment, removes tournaments past their post-finish display window, and excludes tournaments not yet published. SDK consumers receive only items the user is eligible to see; no client-side gating is required. **Reading state from the returned item** Drive list bucketing and CTA labels from the SDK-computed booleans (`is_active`, `is_can_register`, `is_cancelled`, `is_finished`, `is_in_progress`, `is_upcoming`), NOT from raw `start_time` / `end_time` comparisons — the booleans encode the canonical lifecycle states and already reflect server-side rules around qualifying scores and late registration. `is_user_registered` is independent of `is_can_register` — a registered user has `is_user_registered: true` and `is_can_register: false`. The `me` block (if present) carries the user's own leaderboard position and score; it's undefined for unregistered users, users without any recorded score, and visitor-mode sessions. The `prize_pool_short` field carries the operator-supplied summary string ("$10,000", "Mixed prizes") for compact card rendering; the full per-place `prizes[]` breakdown is also populated here but is typically rendered only in the detail view via `getTournamentInstanceInfo`. **Cross-references** Tournaments with `is_clan_based: true` group participants by clan — see `getClanTournamentPlayers` for fetching the players list of a specific clan within a clan tournament. The detailed lobby view (with full player leaderboard and prize structure) comes from `getTournamentInstanceInfo`. Tournaments with `custom_section_id` belong to an operator-defined custom section (resolve metadata via `getCustomSections()`). **Cache TTL**: the SDK caches the response for 30 seconds. Cache is fully cleared on login / logout. **Idempotency**: safe. Read-only. Repeated calls within the cache window return a deep-cloned cached array without a network round-trip. **Side effects**: none — pure metadata read. **UI guidance**: see [UI Guide — `getTournamentsList`](../../docs/ui/tournaments/UIGuide_getTournamentsList.md). **Visitor mode**: supported. The same shape is returned, scoped to the brand's public tournament list. Per-user fields (`me`, `is_user_registered`, `registration_status`) are not meaningful. The `onUpdate` callback is accepted but never fires (registration mutations are not supported in visitor mode). ## Example ```ts const tournaments = await window._smartico.api.getTournamentsList({ onUpdate: (refreshed) => { console.log('[smartico] tournament list refreshed — re-render the lobby UI from this array, do not merge with prior state:', refreshed); const justRegistered = refreshed.filter(t => t.is_user_registered); console.log('[smartico] user is now registered in these tournaments:', justRegistered.map(t => t.name)); }, }); // Bucket items by lifecycle state for a tabbed UI. const live = tournaments.filter(t => t.is_in_progress); const upcoming = tournaments .filter(t => t.is_upcoming && !t.is_user_registered) .sort((a, b) => a.start_time - b.start_time); const mine = tournaments.filter(t => t.is_user_registered); const finished = tournaments.filter(t => t.is_finished); console.log('[smartico] render lobby tabs with these counts: live=', live.length, 'upcoming=', upcoming.length, 'mine=', mine.length, 'finished=', finished.length); // Featured tournament: pin to position 0 of the Overview/Top tabs. const featured = tournaments.find(t => t.is_featured && !t.is_cancelled); if (featured) { console.log('[smartico] featured tournament — pin to position 0 of the Overview tab:', featured.name); } // Visitor mode: onUpdate accepted but never fires; re-poll if needed. // const visitorList = await window._smartico.vapi('EN').getTournamentsList(); ``` ### Example response (REAL shape) > Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth. ```json [ { "instance_id": 589489, "tournament_id": 4450, "name": "Old Dragon's Hoard", "description": "