> ## 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

> Understand when to use queries vs subscriptions, and which endpoints map to each other

## Overview

The Codex API offers two ways to get data: **[queries](/concepts/queries)** and **[subscriptions](/concepts/subscriptions)**. 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?

<AccordionGroup>
  <Accordion title="Use a query when..." defaultOpen>
    * 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 a Free plan
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

<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.
</Tip>

## 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.

<div className="nowrap-code-table">
  > **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; `preprocessed` (Solana only) is the earliest signal, surfaced before transaction routing is finalized. Only Solana and Base support levels other than `confirmed`. This replaces the previously separate `onUnconfirmed*` subscriptions.

  ### Token Data

  | Subscription                                                                                  | Query Equivalent                                                              | Description                                        |
  | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------- |
  | [`onPriceUpdated`](/api-reference/subscriptions/onpriceupdated)                               | [`getTokenPrices`](/api-reference/queries/gettokenprices)                     | Price for a single token                           |
  | [`onPricesUpdated`](/api-reference/subscriptions/onpricesupdated)                             | [`getTokenPrices`](/api-reference/queries/gettokenprices)                     | Prices for multiple tokens (up to 25)              |
  | [`onTokenBarsUpdated`](/api-reference/subscriptions/ontokenbarsupdated)                       | [`getTokenBars`](/api-reference/queries/gettokenbars)                         | Token-level OHLCV bars                             |
  | [`onDetailedTokenStatsUpdated`](/api-reference/subscriptions/ondetailedtokenstatsupdated)     | [`getDetailedTokenStats`](/api-reference/queries/getdetailedtokenstats)       | Detailed token statistics                          |
  | [`onTokenEventsCreated`](/api-reference/subscriptions/ontokeneventscreated)                   | [`getTokenEvents`](/api-reference/queries/gettokenevents)                     | Swap/trade events for a token                      |
  | [`onTokenLifecycleEventsCreated`](/api-reference/subscriptions/ontokenlifecycleeventscreated) | [`tokenLifecycleEvents`](/api-reference/queries/tokenlifecycleevents)         | Token lifecycle events (mint, burn, etc.)          |
  | [`onFilterTokensUpdated`](/api-reference/subscriptions/onfiltertokensupdated)                 | [`filterTokens`](/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.
  </Note>

  ### Pair Data

  | Subscription                                                                    | Query Equivalent                                                      | Description                               |
  | ------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------- |
  | [`onBarsUpdated`](/api-reference/subscriptions/onbarsupdated)                   | [`getBars`](/api-reference/queries/getbars)                           | Pair-level OHLCV bars                     |
  | [`onDetailedStatsUpdated`](/api-reference/subscriptions/ondetailedstatsupdated) | [`getDetailedPairStats`](/api-reference/queries/getdetailedpairstats) | Detailed pair statistics                  |
  | [`onPairMetadataUpdated`](/api-reference/subscriptions/onpairmetadataupdated)   | [`pairMetadata`](/api-reference/queries/pairmetadata)                 | Pair metadata (volume, liquidity, supply) |

  ### Events

  | Subscription                                                                    | Query Equivalent                                                          | Description                              |
  | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------- |
  | [`onEventsCreated`](/api-reference/subscriptions/oneventscreated)               | [`getTokenEvents`](/api-reference/queries/gettokenevents)                 | Trade events for a pair                  |
  | [`onEventsCreatedByMaker`](/api-reference/subscriptions/oneventscreatedbymaker) | [`getTokenEventsForMaker`](/api-reference/queries/gettokeneventsformaker) | Trades by a specific wallet              |
  | [`onEventLabelCreated`](/api-reference/subscriptions/oneventlabelcreated)       | [`getEventLabels`](/api-reference/queries/geteventlabels)                 | Event labels (sandwich, front-run, etc.) |

  ### Balances & Holders

  | Subscription                                                        | Query Equivalent                              | Description               |
  | ------------------------------------------------------------------- | --------------------------------------------- | ------------------------- |
  | [`onHoldersUpdated`](/api-reference/subscriptions/onholdersupdated) | [`holders`](/api-reference/queries/holders)   | Token holder list updates |
  | [`onBalanceUpdated`](/api-reference/subscriptions/onbalanceupdated) | [`balances`](/api-reference/queries/balances) | Wallet balance updates    |

  ### Launchpads

  | Subscription                                                                            | Query Equivalent                                                               | Description                       |
  | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------- |
  | [`onLaunchpadTokenEvent`](/api-reference/subscriptions/onlaunchpadtokenevent)           | [`filterTokens`](/api-reference/queries/filtertokens) (with launchpad filters) | Individual launchpad token events |
  | [`onLaunchpadTokenEventBatch`](/api-reference/subscriptions/onlaunchpadtokeneventbatch) | [`filterTokens`](/api-reference/queries/filtertokens) (with launchpad filters) | Batched launchpad token events    |
</div>