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

# Get Usage

> Retrieve customer usage data for billing periods

<Info>
  Minimum required API key scope: `Read`
</Info>

## Description

Retrieves customer usage data including credits, queries, dashboards, and storage. Returns the current billing period when no timeframe is specified.

## Pricing

This is a metadata endpoint and does not consume credits.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.dune.com/api/v1/usage" \
    -H "Content-Type: application/json" \
    -H "X-DUNE-API-KEY: YOUR_API_KEY" \
    -d '{
      "start_date": "2025-01-01",
      "end_date": "2025-02-01"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.dune.com/api/v1/usage"
  headers = {
      "X-DUNE-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "start_date": "2025-01-01",
      "end_date": "2025-02-01"
  }

  response = requests.post(url, json=data, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = 'https://api.dune.com/api/v1/usage';

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-DUNE-API-KEY': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      start_date: '2025-01-01',
      end_date: '2025-02-01'
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "private_queries": 100,
    "private_dashboards": 100,
    "bytes_used": 1000,
    "bytes_allowed": 10101,
    "billingPeriods": [
      {
        "start_date": "2025-01-01",
        "end_date": "2025-02-01",
        "credits_used": 100.10,
        "credits_included": 100000
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /v1/usage
openapi: 3.0.1
info:
  contact: {}
  description: Dune API
  title: DuneAPI
  version: '1.0'
servers:
  - url: https://api.dune.com/api
security: []
paths:
  /v1/usage:
    post:
      summary: Get Usage Data
      description: >-
        Get usage data for the authenticated customer including private queries,
        dashboards,

        bytes used/allowed, and billing periods
      parameters:
        - description: API Key for the service
          in: header
          name: X-Dune-Api-Key
          required: true
          schema:
            type: string
        - description: API Key, alternative to using the HTTP header X-Dune-Api-Key
          in: query
          name: api_key
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.GetUsageRequest'
        description: Request payload with optional start_date and end_date
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.GetUsageResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error401'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error403'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error500'
          description: Internal Server Error
components:
  schemas:
    models.GetUsageRequest:
      properties:
        end_date:
          description: Optional field in YYYY-MM-DD format
          type: string
        start_date:
          description: Optional field in YYYY-MM-DD format
          type: string
      type: object
    models.GetUsageResponse:
      properties:
        billing_periods:
          items:
            $ref: '#/components/schemas/models.BillingPeriod'
          type: array
        bytes_allowed:
          type: integer
        bytes_used:
          type: integer
        private_dashboards:
          type: integer
        private_queries:
          type: integer
      type: object
    models.Error400:
      properties:
        error:
          example: Bad Request
          type: string
      type: object
    models.Error401:
      properties:
        error:
          example: Invalid API Key
          type: string
      type: object
    models.Error403:
      properties:
        error:
          example: >-
            Not allowed to execute query. Query is archived, unsaved or not
            enough permissions
          type: string
      type: object
    models.Error500:
      properties:
        error:
          example: Internal error
          type: string
      type: object
    models.BillingPeriod:
      properties:
        credits_included:
          description: Float value
          type: number
        credits_used:
          description: Float value
          type: number
        end_date:
          description: YYYY-MM-DD format
          type: string
        start_date:
          description: YYYY-MM-DD format
          type: string
      type: object

````