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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.