List Billing Insights

get/v2/billing/{account_urn}/insights/{start_date}/{end_date}

This endpoint returns day-over-day changes in billing resource usage based on nightly invoice items, including total amount, region, SKU, and description for a specified date range. It is important to note that the daily resource usage may not reflect month-end billing totals when totaled for a given month as nightly invoice item estimates do not necessarily encompass all invoicing factors for the entire month.

Path ParametersExpand Collapse

account_urn: string

start_date: string

formatdate

end_date: string

formatdate

Query ParametersExpand Collapse

page: optional number

Which 'page' of paginated results to return.

minimum1

per_page: optional number

Number of items returned per page

minimum1

maximum200

ReturnsExpand Collapse

current_page: number

Current page number

data_points: array of object { description, group_description, region, 4 more }

Array of billing data points, which are day-over-day changes in billing resource usage based on nightly invoice item estimates, for the requested period

description: optional string

Description of the billed resource or service as shown on an invoice item

group_description: optional string

Optional invoice item group name of the billed resource or service, blank when not part an invoice item group

region: optional string

Region where the usage occurred

sku: optional string

Unique SKU identifier for the billed resource

start_date: optional string

Start date of the billing data point in YYYY-MM-DD format

formatdate

total_amount: optional string

Total amount for this data point in USD

usage_team_urn: optional string

URN of the team that incurred the usage

total_items: number

Total number of items available across all pages

total_pages: number

Total number of pages available

List Billing Insights

curl https://api.digitalocean.com/v2/billing/$ACCOUNT_URN/insights/$START_DATE/$END_DATE \
    -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN"

{
  "current_page": 1,
  "data_points": [
    {
      "description": "droplet name (c-2-4GiB)",
      "group_description": "kubernetes cluster name",
      "region": "nyc3",
      "sku": "1-DO-DROP-0109",
      "start_date": "2025-01-15",
      "total_amount": "12.45",
      "usage_team_urn": "do:team:12345678-1234-1234-1234-123456789012"
    }
  ],
  "total_items": 250,
  "total_pages": 3
}

Returns Examples

{
  "current_page": 1,
  "data_points": [
    {
      "description": "droplet name (c-2-4GiB)",
      "group_description": "kubernetes cluster name",
      "region": "nyc3",
      "sku": "1-DO-DROP-0109",
      "start_date": "2025-01-15",
      "total_amount": "12.45",
      "usage_team_urn": "do:team:12345678-1234-1234-1234-123456789012"
    }
  ],
  "total_items": 250,
  "total_pages": 3
}