Skip to main content

​
Overview

Every GraphQL query consumes Credit Units (CU) based on the Cube queried, the number of rows requested, and the complexity of aggregation. Credits are deducted from the same billing plan as the REST API — your API Key works across both.
The GraphQL API shares the same API Key and billing plan as the REST Data API. Credits consumed by GraphQL queries count toward your overall usage.

​
Credit Calculation Formula

Credits are calculated per Cube using the following formula: 
Credits = BaseCost × LimitFactor × AggregationFactor × MetricFactor
FactorCalculationDescription
BaseCostPer-Cube base price (see table below)Fixed cost that varies by Cube complexity
LimitFactorceil(limit / 100), minimum 1Scales with the number of rows requested
AggregationFactor1.0 (none), 1.5 (GROUP BY), 2.0 (HAVING)Higher for queries using aggregation or HAVING filters
MetricFactor1.0 + (metric_count × 0.2)Increases with each additional metric (count, sum, etc.)
A simple query with default limit (25 rows) and no aggregation pays only the base cost. Credits increase when you request more rows or add aggregation metrics.

​
Calculation Examples

BaseCost = 50, LimitFactor = ceil(10/100) = 1
AggregationFactor = 1.0, MetricFactor = 1.0
Credits = 50 × 1 × 1.0 × 1.0 = 50 CU

BaseCost = 50, LimitFactor = ceil(500/100) = 5
AggregationFactor = 1.0, MetricFactor = 1.0
Credits = 50 × 5 × 1.0 × 1.0 = 250 CU

BaseCost = 50, LimitFactor = ceil(500/100) = 5
AggregationFactor = 1.5 (GROUP BY), MetricFactor = 1.0 + 2×0.2 = 1.4
Credits = 50 × 5 × 1.5 × 1.4 = 525 CU

​
Base Cost per Cube

CubeBase Cost (CU)Notes
DEXTrades50Largest table with most dimensions
DEXTradeByTokens50Same underlying data as DEXTrades
DEXPoolEvents30Liquidity events
Pairs30OHLC candlestick data (Trading group)
Tokens30Token trade statistics (Trading group)
WalletTokenPnL25DWS summary
Transfers15
BalanceUpdates10
Events, Calls20EVM-only trace/event data
Instructions20Solana-only
PredictionTrades20Prediction market data
All other Cubes20Default base cost
Base costs reflect query complexity and the underlying data volume of each Cube. The actual Cube name reported in extensions.credits is determined by the server — always use the response value as the authoritative billing reference.

​
Response: extensions.credits

Every GraphQL response includes credit consumption details in the extensions field: 
{
  "data": {
    "DEXTrades": [ ... ]
  },
  "extensions": {
    "credits": {
      "total": 50,
      "cubes": [
        {
          "cube": "DEXTrades",
          "credits": 50,
          "row_count": 10
        }
      ]
    }
  }
}
FieldTypeDescription
totalIntTotal credits consumed by the entire query
cubesArrayPer-Cube breakdown
cubes[].cubeStringCube name
cubes[].creditsIntCredits charged for this Cube
cubes[].row_countIntNumber of rows returned
The extensions.credits field is present when credits are consumed (i.e., total > 0). Queries that return zero rows still incur the base cost.

​
Monitoring Usage in the IDE

The GraphQL IDE status bar displays credit consumption after each query:
  • CU indicator: Displays the total CU consumed (e.g., 50 CU)
  • Latency: Request duration in milliseconds
  • Response size: Payload size

​
Tips for Optimizing Credit Usage

Select Fewer Fields

Only request the dimensions you need. Fewer fields means less data processed.

Use Appropriate Limits

Keep limit.count as low as practical. Credits scale with ceil(limit / 100).

Use Pre-aggregated Cubes

For aggregated data, prefer DWM/DWS Cubes (Pairs, Tokens, TokenHolders) over running metrics on DWD Cubes (DEXTrades).

General Billing & Units

Overview of ChainStream billing plans, unit quotas, and payment methods.

Metrics & Aggregation

Learn how aggregation metrics affect query credits.