# 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](https://betterstack.com/settings/usage ";_blank") in your billing settings.

The usage API requires a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-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](https://betterstack.com/docs/uptime/api/usage/per-product/).

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

[endpoint]
base_url = "https://betterstack.com"
path = "/api/v2/usage"
method = "GET"

[[query_param]]
name = "from"
description = "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."
required = false
type = "string"

[[query_param]]
name = "to"
description = "End date in the `YYYY-MM-DD` format, inclusive. Defaults to today. Future dates are clamped to today."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = '''Returns each product with its incurred cost over the range and its queryable dimensions.'''
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": "$" }
        ]
      }
    }
  ]
}'''

[[response]]
status = 401
description = '''Authentication failed due to a missing or invalid token.'''
body = '''{
  "errors": "We could not authenticate your request. Please provide a valid Global API token."
}'''

[[response]]
status = 429
description = '''Rate limit exceeded. Wait before retrying.'''
[/responses]

#### Example cURL

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