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

# Circulating Supply Chart within Time Range by ID

> To query historical circulating supply of a coin, within a range of timestamp based on the provided coin ID

export const CacheInfo = ({publicRate, paidRate, rate}) => {
  const fmt = v => v === 0 ? 'Real-time (Cacheless)' : `Every ${v}`;
  if (rate !== undefined) {
    return <Callout icon="clock-rotate-left" color="#2196F3" iconType="regular">
        <strong>Cache / Update Frequency:</strong><br />{fmt(rate)}
      </Callout>;
  }
  if (publicRate !== undefined && paidRate !== undefined) {
    return <Callout icon="clock-rotate-left" color="#2196F3" iconType="regular">
        <strong>Cache / Update Frequency:</strong><ul><li>{fmt(paidRate)} (Paid API)</li><li>{fmt(publicRate)} (Demo / Keyless API)</li></ul>
      </Callout>;
  }
  return null;
};

export const PlanExclusivity = ({tier}) => {
  if (tier === "enterprise") {
    return <Callout icon="crown" color="#FFC107" iconType="regular">
        <strong>Enterprise Only</strong><br />This endpoint is exclusively available to <strong>Enterprise</strong> plan.<br /><a href="https://www.coingecko.com/en/api/enterprise">→ Contact sales</a>
      </Callout>;
  }
  if (tier === "analyst_above") {
    return <Callout icon="briefcase" color="#FFC107" iconType="regular">
        <strong>Analyst Plan and Above</strong><br />This endpoint is only available to <strong>Analyst, Lite, Pro, and Enterprise</strong> plan.<br /><a href="https://www.coingecko.com/en/api/pricing">→ View pricing</a>
      </Callout>;
  }
  if (tier === "basic_above") {
    return <Callout icon="briefcase" color="#FFC107" iconType="regular">
        <strong>Basic Plan and Above</strong><br />This endpoint is only available to <strong>Basic, Analyst, Lite, Pro, and Enterprise</strong> plan.<br /><a href="https://www.coingecko.com/en/api/pricing">→ View pricing</a>
      </Callout>;
  }
  throw new Error(`PlanExclusivity: invalid tier "${tier}". Use "basic_above", "analyst_above", or "enterprise".`);
};

#### Notes

* Accepts ISO date strings (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`, recommended) or UNIX timestamps for `from` and `to`.
* Auto-granularity when `interval` is not specified:
  * 1 day from current time = **5-minutely** data
  * 1 day from any other time = **hourly** data
  * 2–90 days = **hourly** data
  * Above 90 days = **daily** data (00:00 UTC)
* Data available from 22 June 2019 onwards.

<Note>
  The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC).
</Note>

<PlanExclusivity tier="enterprise" />

<CacheInfo rate="5 minutes" />

#### SDK Examples

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await client.coins.circulatingSupplyChart.getRange('bitcoin', {
    from: '2025-01-01',
    to: '2025-12-31',
  });

  console.log(JSON.stringify(response, null, 2));
  ```

  ```python Python theme={null}
  response = client.coins.circulating_supply_chart.get_range(
    "bitcoin",
    from_="2025-01-01",
    to="2025-12-31",
  )

  print(response.model_dump_json(indent=2))
  ```
</CodeGroup>


## OpenAPI

````yaml openapi-specs/pro-api.json get /coins/{id}/circulating_supply_chart/range
openapi: 3.0.0
info:
  title: CoinGecko Pro API
  version: 3.0.0
servers:
  - url: https://pro-api.coingecko.com/api/v3
security:
  - headerAuth: []
  - queryAuth: []
paths:
  /coins/{id}/circulating_supply_chart/range:
    get:
      summary: Circulating Supply Chart within Time Range by ID
      description: >-
        To query historical circulating supply of a coin, within a range of
        timestamp based on the provided coin ID
      operationId: coins-id-circulating-supply-chart-range
      parameters:
        - name: id
          in: path
          required: true
          description: |-
            Coin ID. 
            *refers to [`/coins/list`](/reference/coins-list).
          schema:
            type: string
            default: bitcoin
        - name: from
          in: query
          required: true
          description: >-
            Starting date in ISO date string (`YYYY-MM-DD` or
            `YYYY-MM-DDTHH:MM`) or UNIX timestamp. 

            **Use ISO date string for best compatibility.**
          schema:
            type: string
            default: '2025-01-01'
        - name: to
          in: query
          required: true
          description: >-
            Ending date in ISO date string (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`)
            or UNIX timestamp. 

            **Use ISO date string for best compatibility.**
          schema:
            type: string
            default: '2025-12-31'
      responses:
        '200':
          description: Historical circulating supply chart data within time range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CirculatingSupplyChart'
              example:
                circulating_supply:
                  - - 1735689600000
                    - '19803921.0'
                  - - 1735776000000
                    - '19804340.0'
                  - - 1735862400000
                    - '19804871.0'
components:
  schemas:
    CirculatingSupplyChart:
      type: object
      required:
        - circulating_supply
      properties:
        circulating_supply:
          type: array
          description: Circulating supply data points as [timestamp, supply] pairs
          items:
            type: array
            items:
              oneOf:
                - type: number
                - type: string
  securitySchemes:
    headerAuth:
      type: apiKey
      in: header
      name: x-cg-pro-api-key
      description: >-
        Learn how to [set up your API
        key](https://docs.coingecko.com/docs/setting-up-your-api-key)
    queryAuth:
      type: apiKey
      in: query
      name: x_cg_pro_api_key
      description: >-
        Learn how to [set up your API
        key](https://docs.coingecko.com/docs/setting-up-your-api-key)

````