Explore documentation
  1. Welcome to Uptime 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Connecting external calendars
    4. Advanced guide
  4. Incidents
    1. Get started
    2. Post mortems
    3. Metadata & Catalog
    4. Screening alerts
    5. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Uptime API
    1. Getting an API token
    2. Monitors
    3. Heartbeats
    4. On-call & incidents
    5. Status pages
    6. Metadata
    7. Integrations
    8. Team members
    9. Organization roles
    10. Usage
      1. Get usage overview
      2. Get usage per product
    11. Reporting

Get usage overview

Retrieve your organization's usage and incurred cost across Better Stack products, itemized down to individual sources, applications, and billing line items. The usage API returns the same data as the Usage page in your billing settings.

The usage API requires a global API token.

This endpoint lists every product your organization uses, its incurred cost over the date range, and the dimensions you can query it by. The product id values, dimension names, and default_dimension values are the inputs for getting usage per product.

Time range defaults to the last 30 days when from and to are omitted and results are returned without pagination.

GET https://betterstack.com/api/v2/usage

Query parameters

from
string

Start date in the YYYY-MM-DD format, inclusive. Defaults to 29 days before to. The range between from and to can span at most 400 days.

to
string

End date in the YYYY-MM-DD format, inclusive. Defaults to today. Future dates are clamped to today.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns each product with its incurred cost over the range and its queryable dimensions.

Response body

{
  "meta": {
    "from": "2026-06-30",
    "to": "2026-07-29"
  },
  "data": [
    {
      "id": "logs",
      "type": "usage_product",
      "attributes": {
        "name": "Logs",
        "cost": 267.4,
        "default_dimension": "volume",
        "dimensions": [
          {
            "name": "volume",
            "label": "Ingested volume",
            "unit": "bytes"
          },
          {
            "name": "retention",
            "label": "Retention",
            "unit": "days"
          },
          {
            "name": "region",
            "label": "Regions",
            "unit": "text"
          },
          {
            "name": "cost",
            "label": "Incurred cost",
            "unit": "$"
          }
        ]
      }
    },
    {
      "id": "monitors",
      "type": "usage_product",
      "attributes": {
        "name": "Monitors",
        "cost": 81.25,
        "default_dimension": "Monitors",
        "dimensions": [
          {
            "name": "Monitors",
            "label": "Monitors",
            "unit": "count"
          },
          {
            "name": "cost",
            "label": "Incurred cost",
            "unit": "$"
          }
        ]
      }
    }
  ]
}
401

Authentication failed due to a missing or invalid token.

Response body

{
  "errors": "We could not authenticate your request. Please provide a valid Global API token."
}
429

Rate limit exceeded. Wait before retrying.

Example cURL

Usage overview
curl --request GET \
  --url "https://betterstack.com/api/v2/usage" \
  --header "Authorization: Bearer $TOKEN"


Previous article

List roles

Next article

Get usage per product