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

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