Billing & Credits

Understand how GraphQL API queries are billed using the Credit Unit system

Overview

Every GraphQL query consumes Credit Units (CU) that are dynamically calculated based on the query’s complexity. 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 a 5-factor formula. The final CU depends on what you query, how many rows you request, whether you use aggregation, how many metrics you include, and how many fields you select.

CU = ceil(BaseCost × LimitFactor × AggregationFactor × MetricFactor × ComplexityFactor) / 100

Factor	Calculation	Description
BaseCost	Per-Cube internal value	Reflects the underlying table size and scan cost. Each Cube has a different base cost.
LimitFactor	ceil(limit / 100), minimum 1	Scales linearly with the number of rows requested. Requesting 1–100 rows costs the same; 101–200 costs 2×, etc.
AggregationFactor	1.0 (none), 1.5 (GROUP BY), 2.0 (HAVING)	Higher for queries that use aggregation or post-aggregation filters (selectWhere).
MetricFactor	1.0 + (aggregate_count × 0.1)	Each additional aggregation function (count, sum, avg, etc.) adds 10% to the cost.
ComplexityFactor	min(1.0 + min(select_count, 250) / 50 × 0.2, 1.5)	Selecting more fields increases cost, capped at 1.5×. A simple query with ~5 fields has a factor of ~1.02.

Zero-row queries are free. If a query returns no rows, no credits are charged regardless of the other factors.

Calculation Examples

Simple query: 10 rows, 5 fields

BaseCost = 2000 (internal), LimitFactor = ceil(10/100) = 1
AggregationFactor = 1.0, MetricFactor = 1.0
ComplexityFactor = 1.0 + (5/50) × 0.2 = 1.02
Internal = ceil(2000 × 1 × 1.0 × 1.0 × 1.02) = 2040
CU = 2040 / 100 = 20.40 CU

Large query: 500 rows, 5 fields

BaseCost = 2000, LimitFactor = ceil(500/100) = 5
AggregationFactor = 1.0, MetricFactor = 1.0
ComplexityFactor = 1.02
Internal = ceil(2000 × 5 × 1.0 × 1.0 × 1.02) = 10200
CU = 10200 / 100 = 102.00 CU

Aggregation query: GROUP BY + 2 metrics, 500 rows

BaseCost = 2000, LimitFactor = ceil(500/100) = 5
AggregationFactor = 1.5 (GROUP BY)
MetricFactor = 1.0 + 2 × 0.1 = 1.2
ComplexityFactor = 1.02
Internal = ceil(2000 × 5 × 1.5 × 1.2 × 1.02) = 18360
CU = 18360 / 100 = 183.60 CU

Complex query: many fields selected

BaseCost = 2000, LimitFactor = 1
AggregationFactor = 1.0, MetricFactor = 1.0
ComplexityFactor = min(1.0 + (250/50) × 0.2, 1.5) = 1.5 (capped)
Internal = ceil(2000 × 1 × 1.0 × 1.0 × 1.5) = 3000
CU = 3000 / 100 = 30.00 CU

Since CU is dynamically calculated, the best way to know the exact cost of a query is to check the extensions.credits field in the response, or monitor the CU indicator in the IDE status bar.

---

Response: extensions.credits

Every GraphQL response includes credit consumption details in the extensions field:

{
  "data": {
    "Solana": {
      "DEXTrades": [ ... ]
    }
  },
  "extensions": {
    "credits": {
      "total": 20.4,
      "unit": "CU",
      "cubes": [
        {
          "cube": "DEXTrades",
          "credits": 20.4,
          "row_count": 10
        }
      ]
    }
  }
}

Field	Type	Description
total	Float	Total CU consumed by the entire query
unit	String	Always "CU"
cubes	Array	Per-Cube breakdown
cubes[].cube	String	Cube name as used by the billing engine
cubes[].credits	Float	CU charged for this Cube
cubes[].row_count	Int	Number of rows returned

The extensions.credits field is present when credits are consumed (i.e., total > 0). Queries that return zero rows are not charged.

---

Monitoring Usage in the IDE

The GraphQL IDE status bar displays credit consumption after each query:

• CU indicator: Displays the total CU consumed
• Latency: Request duration in milliseconds
• Response size: Payload size

---

Tips for Optimizing Credit Usage

Select Fewer Fields

Only request the dimensions you need. The ComplexityFactor increases with the number of selected fields.

Use Appropriate Limits

Keep limit.count as low as practical. The LimitFactor doubles for every 100 additional rows.

Use Pre-aggregated Cubes

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

---

Related Documentation

General Billing & Units

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

Metrics & Aggregation

Learn how aggregation metrics affect query credits.