> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Info>
  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.
</Info>

***

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

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

### Calculation Examples

<AccordionGroup>
  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  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.
</Tip>

***

## Response: `extensions.credits`

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

```json theme={null}
{
  "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                 |

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

***

## Monitoring Usage in the IDE

The [GraphQL IDE](https://ide.chainstream.io) 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

<CardGroup cols={3}>
  <Card title="Select Fewer Fields" icon="minimize">
    Only request the dimensions you need. The ComplexityFactor increases with the number of selected fields.
  </Card>

  <Card title="Use Appropriate Limits" icon="gauge">
    Keep `limit.count` as low as practical. The LimitFactor doubles for every 100 additional rows.
  </Card>

  <Card title="Use Pre-aggregated Cubes" icon="layer-group">
    For aggregated data, prefer DWM/DWS Cubes (Pairs, Tokens, TokenHolders) over running metrics on DWD Cubes (DEXTrades).
  </Card>
</CardGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="General Billing & Units" icon="receipt" href="/en/docs/platform/billing-payments/plans-and-units">
    Overview of ChainStream billing plans, unit quotas, and payment methods.
  </Card>

  <Card title="Metrics & Aggregation" icon="chart-simple" href="/en/graphql/schema/metrics-aggregation">
    Learn how aggregation metrics affect query credits.
  </Card>
</CardGroup>