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

> On-demand data requests — the basic building block of the Codex API

export const EmbedFrame = ({query, height, caption}) => {
  const encodedQuery = typeof window === "undefined" ? "" : encodeURIComponent(query);
  return <Frame caption={caption}>
      <div style={{
    width: "100%",
    height: height || "100%",
    minHeight: "400px",
    maxHeight: "90vh",
    position: "relative",
    display: "flex",
    flexDirection: "column",
    flex: "1"
  }}>
        <iframe src={"https://explorer.codex.io/embed.html?query=" + encodedQuery} width="100%" className="w-full aspect-video rounded-xl" style={{
    flex: "1",
    height: "100%",
    borderRadius: "12px",
    border: "none",
    display: "block"
  }} />
      </div>
    </Frame>;
};

## What is a Query?

A query is a one-time request for data. You send a GraphQL query to the Codex API over HTTP, and you get back a response with the data you asked for. Queries are the standard way to fetch token prices, wallet stats, historical bars, holder lists, and everything else in the API.

**Every query you run counts as 1 request** against your plan's monthly limit.

<Tip>
  Not sure whether to use a query or a subscription? See [Queries vs Subscriptions](/extra/queries-vs-subscriptions) for a side-by-side comparison and endpoint mapping.
</Tip>

## When to Use Queries

* **Fetching current state** — token prices, metadata, pair stats, wallet balances
* **Historical data** — OHLCV bars, trade events, wallet charts
* **Paginated lists** — filtering tokens, wallets, pairs, or events with cursor-based pagination
* **One-time lookups** — loading a page, responding to a user action, backfilling data

If you need data pushed to you continuously in real-time (e.g. live price feeds or streaming trades), use [Subscriptions](/concepts/subscriptions) instead.

## How It Works

Send a `POST` request to `https://graph.codex.io/graphql` with your API key in the `Authorization` header.

To see a reference of all available queries, go to the [API Reference](/api-reference/introduction).

## Examples

<AccordionGroup>
  <Accordion title="Try it" defaultOpen>
    <EmbedFrame
      query={`
  query {
    getTokenPrices(inputs: [{ address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c", networkId: 56 }]) {
      priceUsd
      timestamp
      address
    }
  }
`}
    />
  </Accordion>

  <Accordion title="SDK">
    ```typescript theme={null}
    import { Codex } from "@codex-data/sdk"

    const sdk = new Codex("your-api-key")

    const { getTokenPrices } = await sdk.query(gql`
      query {
        getTokenPrices(inputs: [{ address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c", networkId: 56 }]) {
          priceUsd
          timestamp
          address
        }
      }
    `)
    ```
  </Accordion>

  <Accordion title="Custom">
    <CodeGroup>
      ```typescript js theme={null}
      fetch("https://graph.codex.io/graphql", {
        method: "POST",
        headers: {
          "Authorization": apiKey,
        },
        body: JSON.stringify({ query: 'query { getTokenPrices(inputs: [{ address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c", networkId: 56 }]) { priceUsd timestamp address } }' }),
      })
      ```

      ```python python theme={null}
      import requests
      import json

      url = "https://graph.codex.io/graphql"

      headers = {
        "content_type":"application/json",
        "Authorization": "<MY_KEY>"
      }

      getNetworks = """query GetNetworksQuery { getNetworks { name id } }"""

      response = requests.post(url, headers=headers, json={"query": getNetworks})

      print(json.loads(response.text))
      ```

      ```php php theme={null}
      <?php

      $url = "https://graph.codex.io/graphql";

      $query = array(
          'query' => '{
              getNetworks {
                  name
                  id
              }
          }'
      );

      $headers = array(
          'Content-Type: application/json',
          'Authorization: ' . "<MY_KEY>"
      );

      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($query));
      curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

      $response = curl_exec($ch);
      curl_close($ch);

      echo $response;
      ```

      ```go go theme={null}
      package main

      import (
        "bytes"
        "fmt"
        "net/http"
        "io/ioutil"
        "encoding/json"
      )

      func main() {
        url := "https://graph.codex.io/graphql"
        apiKey := "<MY_KEY>"

        query := `query GetNetworksQuery { getNetworks { name id } }`
        payload := map[string]string{"query": query}
        payloadBytes, _ := json.Marshal(payload)

        req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payloadBytes))
        req.Header.Set("Content-Type", "application/json")
        req.Header.Set("Authorization", apiKey)

        client := &http.Client{}
        res, _ := client.Do(req)
        defer res.Body.Close()

        body, _ := ioutil.ReadAll(res.Body)

        var response map[string]interface{}
        json.Unmarshal(body, &response)

        fmt.Println(response)
      }

      ```

      ```ruby ruby theme={null}
      require 'net/http'
      require 'json'

      uri = URI('https://graph.codex.io/graphql')
      http = Net::HTTP.new(uri.host, uri.port)
      http.use_ssl = true

      headers = {
        'Content-Type' => 'application/json',
        'Authorization' => '<MY_KEY>'
      }

      query = {
        query: '{
          getNetworks {
            name
            id
          }
        }'
      }

      request = Net::HTTP::Post.new(uri.path, headers)
      request.body = query.to_json

      response = http.request(request)
      puts response.body
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>