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 in your billing settings.

The usage API requires 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.

GET https://betterstack.com/api/v2/usage/{product}

URL parameters

product

required string

The product id from the usage overview, for example logs, traces, metrics, or monitors.

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.

string

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

dimension

string

A dimension name from the 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.

resolution

string

Bucket size: day, week, month, or quarter. Defaults to day.

Headers

Authorization

required string

Bearer $TOKEN

200

Returns one entry per item with a value for every bucket in the range.

Response 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
          }
        ]
      }
    }
  ]
}

200

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.

Response 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
          }
        ]
      }
    }
  ]
}

200

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.

Response 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
          }
        ]
      }
    }
  ]
}

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."
}

404

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.

Response body

{
  "errors": "Product not found. Available products: logs, traces, metrics, monitors, heartbeats, status-pages."
}

422

An invalid parameter: a malformed date, a from after to, an unknown resolution or query parameter, or a range over 400 days.

Response body

{
  "errors": "Date range too large. Use at most 400 days."
}

Response attributes

meta.product

string

The product ID.

meta.dimension

string

The dimension the values measure, or cost for the incurred cost.

meta.label

string

The human-readable name of the dimension.

meta.unit

string

The unit of every value, for example bytes, count, text, or $ for cost.

meta.resolution

string

The bucket size: day, week, month, or quarter.

meta.from

string

The first day of the date range, in the YYYY-MM-DD format.

meta.to

string

The last day of the date range, in the YYYY-MM-DD format.

string

The ID of the item, such as a source or application ID, or a name for items without a numbered object behind them.

type

string

The item type, built from the product ID and the dimension, for example usage_logs_volume_item or usage_transaction_monitors_cost_item.

attributes.name

string

The name of the item, or the name of the dimension or product when the item can't be resolved to one.

attributes.url

string or null

A link to the item in Better Stack, or null when there is none.

attributes.values

array

One entry per bucket in the range, oldest first.

attributes.values[].date

string

The day of the bucket, in the YYYY-MM-DD format, with the day resolution only.

attributes.values[].date_from

string

The first day of the bucket, in the YYYY-MM-DD format, with resolutions other than day.

attributes.values[].date_to

string

The last day of the bucket, in the YYYY-MM-DD format, with resolutions other than day.

attributes.values[].value

number or null

The usage or cost in the bucket, in meta.unit and 0 when there was none, except with the text unit, which returns a string or null.

attributes.values[].finalized

boolean

Whether the bucket ended before today, so its value won't change.

Example cURL

Log volume Responders Weekly report

Copied!

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

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

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"

Get usage overview

Incident log drain

Explore documentation

Get usage per product

Example cURL

Please accept cookies