Billing & Credits

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

General Billing & Units

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

Metrics & Aggregation

Learn how aggregation metrics affect query credits.

Getting Started

GraphQL IDE

Schema & Data Model

Query Examples

Billing & Credits

Overview

Credit Calculation Formula

Calculation Examples

Response: `extensions.credits`

Monitoring Usage in the IDE

Tips for Optimizing Credit Usage

Select Fewer Fields

Use Appropriate Limits

Use Pre-aggregated Cubes

General Billing & Units

Metrics & Aggregation

​Overview

​Credit Calculation Formula

​Calculation Examples

​Response: extensions.credits

​Monitoring Usage in the IDE

​Tips for Optimizing Credit Usage

Select Fewer Fields

Use Appropriate Limits

Use Pre-aggregated Cubes

​Related Documentation

General Billing & Units

Metrics & Aggregation

Overview

Credit Calculation Formula

Calculation Examples

Response: `extensions.credits`

Monitoring Usage in the IDE

Tips for Optimizing Credit Usage

Related Documentation