> ## Documentation Index > Fetch the complete documentation index at: https://docs.codex.io/llms.txt > Use this file to discover all available pages before exploring further. # Queries vs Subscriptions > When to poll with a query and when to stream with a subscription, plus a map of which Codex queries and subscriptions return the same data. ## Overview The Codex API offers two ways to get data: **[queries](https://docs.codex.io/concepts/queries.md)** and **[subscriptions](https://docs.codex.io/concepts/subscriptions.md)**. Many endpoints have both a query and a subscription version that return the same data — the difference is *how* you receive it. | | Query | Subscription | | - | - | - | | **Protocol** | HTTP (`POST` to `https://graph.codex.io/graphql`) | WebSocket (`wss://graph.codex.io/graphql`) | | **How it works** | You request data, you get a response | You subscribe once, data is pushed to you as it changes | | **Best for** | Page loads, historical data, one-time lookups | Live feeds, real-time dashboards, streaming updates | | **Billing** | 1 request per query execution | 1 request per message received | | **Plan requirement** | All plans | Growth or Enterprise | ## Which Should I Use? > [accordion] Use a query when... > > * You need data once (e.g. loading a page, fetching a wallet's history) > * You need historical data (e.g. OHLCV bars from last week) > * You need to paginate through large result sets (e.g. filtering tokens) > * You're on the Almost free plan > [accordion] Use a subscription when... > > * You need real-time updates (e.g. live price ticker, streaming trades) > * You want data pushed to you instantly as it happens > * You're building a live dashboard or trading bot > * You want to avoid polling the API repeatedly > [!TIP] > > A common pattern is to use a **query to load initial data**, then switch to a **subscription to keep it updated** in real-time. ## Endpoint Mapping The table below maps each subscription to its query equivalent. Both return the same data — the query fetches it on-demand, while the subscription streams updates as they happen. > **Unconfirmed events:** Several subscriptions accept a `commitmentLevel` argument that trades latency against accuracy. `confirmed` (the default) delivers events only after confirmation; `processed` delivers them earlier (unconfirmed; may be reorged out); on Base, `processed` returns Flashblocks events. Only Solana, Base, and Robinhood support levels other than `confirmed`. This replaces the previously separate `onUnconfirmed*` subscriptions. For the fastest `processed` data, use an [edge node](https://docs.codex.io/concepts/edge-nodes.md). ### Token Data | Subscription | Query Equivalent | Description | | - | - | - | | [`onPriceUpdated`](https://docs.codex.io/api-reference/subscriptions/onpriceupdated) | [`getTokenPrices`](https://docs.codex.io/api-reference/queries/gettokenprices) | Price for a single token | | [`onPricesUpdated`](https://docs.codex.io/api-reference/subscriptions/onpricesupdated) | [`getTokenPrices`](https://docs.codex.io/api-reference/queries/gettokenprices) | Prices for multiple tokens (up to 25) | | [`onTokenBarsUpdated`](https://docs.codex.io/api-reference/subscriptions/ontokenbarsupdated) | [`getTokenBars`](https://docs.codex.io/api-reference/queries/gettokenbars) | Token-level OHLCV bars | | [`onDetailedTokenStatsUpdated`](https://docs.codex.io/api-reference/subscriptions/ondetailedtokenstatsupdated) | [`getDetailedTokenStats`](https://docs.codex.io/api-reference/queries/getdetailedtokenstats) | Detailed token statistics | | [`onTokenEventsCreated`](https://docs.codex.io/api-reference/subscriptions/ontokeneventscreated) | [`getTokenEvents`](https://docs.codex.io/api-reference/queries/gettokenevents) | Swap/trade events for a token | | [`onTokenLifecycleEventsCreated`](https://docs.codex.io/api-reference/subscriptions/ontokenlifecycleeventscreated) | [`tokenLifecycleEvents`](https://docs.codex.io/api-reference/queries/tokenlifecycleevents) | Token lifecycle events (mint, burn, etc.) | | [`onFilterTokensUpdated`](https://docs.codex.io/api-reference/subscriptions/onfiltertokensupdated) | [`filterTokens`](https://docs.codex.io/api-reference/queries/filtertokens) (with matching filters) | Live-streamed updates to a filterTokens result set | > [!NOTE] > > `onFilterTokensUpdated` is self-initializing — the first message delivers the current state, so you don't need to pair it with a separate `filterTokens` query. The subscription re-evaluates internally every 30 seconds, and if the result set changes you'll automatically start receiving updates for the new set. ### Pair Data | Subscription | Query Equivalent | Description | | - | - | - | | [`onBarsUpdated`](https://docs.codex.io/api-reference/subscriptions/onbarsupdated) | [`getBars`](https://docs.codex.io/api-reference/queries/getbars) | Pair-level OHLCV bars | | [`onDetailedStatsUpdated`](https://docs.codex.io/api-reference/subscriptions/ondetailedstatsupdated) | [`getDetailedPairStats`](https://docs.codex.io/api-reference/queries/getdetailedpairstats) | Detailed pair statistics | | [`onPairMetadataUpdated`](https://docs.codex.io/api-reference/subscriptions/onpairmetadataupdated) | [`pairMetadata`](https://docs.codex.io/api-reference/queries/pairmetadata) | Pair metadata (volume, liquidity, supply) | ### Events | Subscription | Query Equivalent | Description | | - | - | - | | [`onEventsCreated`](https://docs.codex.io/api-reference/subscriptions/oneventscreated) | [`getTokenEvents`](https://docs.codex.io/api-reference/queries/gettokenevents) | Trade events for a pair | | [`onEventsCreatedByMaker`](https://docs.codex.io/api-reference/subscriptions/oneventscreatedbymaker) | [`getTokenEventsForMaker`](https://docs.codex.io/api-reference/queries/gettokeneventsformaker) | Trades by a specific wallet | | [`onEventLabelCreated`](https://docs.codex.io/api-reference/subscriptions/oneventlabelcreated) | [`getEventLabels`](https://docs.codex.io/api-reference/queries/geteventlabels) | Event labels (sandwich, front-run, etc.) | ### Balances & Holders | Subscription | Query Equivalent | Description | | - | - | - | | [`onHoldersUpdated`](https://docs.codex.io/api-reference/subscriptions/onholdersupdated) | [`holders`](https://docs.codex.io/api-reference/queries/holders) | Token holder list updates | | [`onBalanceUpdated`](https://docs.codex.io/api-reference/subscriptions/onbalanceupdated) | [`balances`](https://docs.codex.io/api-reference/queries/balances) | Wallet balance updates | ### Launchpads | Subscription | Query Equivalent | Description | | - | - | - | | [`onLaunchpadTokenEvent`](https://docs.codex.io/api-reference/subscriptions/onlaunchpadtokenevent) | [`filterTokens`](https://docs.codex.io/api-reference/queries/filtertokens) (with launchpad filters) | Individual launchpad token events | | [`onLaunchpadTokenEventBatch`](https://docs.codex.io/api-reference/subscriptions/onlaunchpadtokeneventbatch) | [`filterTokens`](https://docs.codex.io/api-reference/queries/filtertokens) (with launchpad filters) | Batched launchpad token events | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.