# Get usage per product

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

Buckets align to calendar days, weeks, months, or quarters based on `resolution`, so with a coarser resolution the first and last bucket can extend beyond your requested range. Resolutions other than `day` return a `date_from` and `date_to` instead of a single `date`.

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/{product}"
method = "GET"

[[path_param]]
name = "product"
description = "The product `id` from the [usage overview](https://betterstack.com/docs/uptime/api/usage/overview/), for example `logs`, `traces`, `metrics`, or `monitors`."
required = true
type = "string"

[[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"

[[query_param]]
name = "dimension"
description = "A dimension name from the [usage overview](https://betterstack.com/docs/uptime/api/usage/overview/), or `cost` for the product's incurred cost. Defaults to the product's `default_dimension`. Dimension names vary per product and plan, so discover them through the overview."
required = false
type = "string"

[[query_param]]
name = "resolution"
description = "Bucket size: `day`, `week`, `month`, or `quarter`. Defaults to `day`."
required = false
type = "string"

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

[responses]
[[response]]
status = 200
description = '''Returns one entry per item with a value for every bucket in the range.'''
body = '''{
  "meta": {
    "product": "logs",
    "dimension": "volume",
    "label": "Ingested volume",
    "unit": "bytes",
    "resolution": "day",
    "from": "2026-07-26",
    "to": "2026-07-29"
  },
  "data": [
    {
      "id": "142",
      "type": "usage_logs_volume_item",
      "attributes": {
        "name": "production-app",
        "url": "https://telemetry.betterstack.com/team/t123456/sources/311278/edit",
        "values": [
          { "date": "2026-07-26", "value": 1073741824, "finalized": true },
          { "date": "2026-07-27", "value": 1073741824, "finalized": true },
          { "date": "2026-07-28", "value": 2147483648, "finalized": true },
          { "date": "2026-07-29", "value": 536870912, "finalized": false }
        ]
      }
    },
    {
      "id": "167",
      "type": "usage_logs_volume_item",
      "attributes": {
        "name": "staging-app",
        "url": "https://telemetry.betterstack.com/team/t123456/sources/311292/edit",
        "values": [
          { "date": "2026-07-26", "value": 268435456, "finalized": true },
          { "date": "2026-07-27", "value": 268435456, "finalized": true },
          { "date": "2026-07-28", "value": 0, "finalized": true },
          { "date": "2026-07-29", "value": 134217728, "finalized": false }
        ]
      }
    }
  ]
}'''

[[response]]
status = 200
description = '''Counted dimensions look the same. Here the responder licenses in use and unassigned each day. Items without a numbered object behind them read their `id` as the name.'''
body = '''{
  "meta": {
    "product": "responders",
    "dimension": "seat_id",
    "label": "Responders",
    "unit": "count",
    "resolution": "day",
    "from": "2026-07-26",
    "to": "2026-07-29"
  },
  "data": [
    {
      "id": "Responders",
      "type": "usage_responders_seat_id_item",
      "attributes": {
        "name": "Responders",
        "url": null,
        "values": [
          { "date": "2026-07-26", "value": 12, "finalized": true },
          { "date": "2026-07-27", "value": 12, "finalized": true },
          { "date": "2026-07-28", "value": 13, "finalized": true },
          { "date": "2026-07-29", "value": 13, "finalized": false }
        ]
      }
    },
    {
      "id": "Unassigned licenses",
      "type": "usage_responders_seat_id_item",
      "attributes": {
        "name": "Unassigned licenses",
        "url": null,
        "values": [
          { "date": "2026-07-26", "value": 3, "finalized": true },
          { "date": "2026-07-27", "value": 3, "finalized": true },
          { "date": "2026-07-28", "value": 2, "finalized": true },
          { "date": "2026-07-29", "value": 2, "finalized": false }
        ]
      }
    }
  ]
}'''

[[response]]
status = 200
description = '''With `dimension=cost` and a coarser `resolution`, buckets return a `date_from` and `date_to`, aligned to calendar weeks. Here the transaction monitoring cost over the first 8 weeks of 2026.'''
body = '''{
  "meta": {
    "product": "transaction-monitors",
    "dimension": "cost",
    "label": "Incurred cost",
    "unit": "$",
    "resolution": "week",
    "from": "2026-01-01",
    "to": "2026-02-22"
  },
  "data": [
    {
      "id": "285114",
      "type": "usage_transaction_monitors_cost_item",
      "attributes": {
        "name": "Transaction monitoring",
        "url": null,
        "values": [
          { "date_from": "2025-12-29", "date_to": "2026-01-04", "value": 24.5, "finalized": true },
          { "date_from": "2026-01-05", "date_to": "2026-01-11", "value": 24.5, "finalized": true },
          { "date_from": "2026-01-12", "date_to": "2026-01-18", "value": 26.25, "finalized": true },
          { "date_from": "2026-01-19", "date_to": "2026-01-25", "value": 28.0, "finalized": true },
          { "date_from": "2026-01-26", "date_to": "2026-02-01", "value": 28.0, "finalized": true },
          { "date_from": "2026-02-02", "date_to": "2026-02-08", "value": 28.0, "finalized": true },
          { "date_from": "2026-02-09", "date_to": "2026-02-15", "value": 29.75, "finalized": true },
          { "date_from": "2026-02-16", "date_to": "2026-02-22", "value": 29.75, "finalized": true }
        ]
      }
    }
  ]
}'''

[[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 = 404
description = '''The product `id` doesn't exist or isn't available to your organization. The error lists the available products. The same shape is returned for an unknown `dimension`.'''
body = '''{
  "errors": "Product not found. Available products: logs, traces, metrics, monitors, heartbeats, status-pages."
}'''

[[response]]
status = 422
description = '''An invalid parameter: a malformed date, a `from` after `to`, an unknown `resolution` or query parameter, or a range over 400 days.'''
body = '''{
  "errors": "Date range too large. Use at most 400 days."
}'''
[/responses]

#### Example cURL

[code-tabs]
```shell
[label Log volume]
curl --request GET \
  --url "https://betterstack.com/api/v2/usage/logs" \
  --header "Authorization: Bearer $TOKEN"
```
```shell
[label Responders]
curl --request GET \
  --url "https://betterstack.com/api/v2/usage/responders" \
  --header "Authorization: Bearer $TOKEN"
```
```shell
[label Weekly report]
curl --request GET \
  --url "https://betterstack.com/api/v2/usage/transaction-monitors" \
  --data-urlencode "dimension=cost" \
  --data-urlencode "resolution=week" \
  --data-urlencode "from=2026-01-01" \
  --data-urlencode "to=2026-02-22" \
  --header "Authorization: Bearer $TOKEN"
```
[/code-tabs]