List Billing Insights

billing.list_insights(, ) -> BillingListInsightsResponse

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.

ParametersExpand Collapse

account_urn: str

start_date: Union[null, null]

formatdate

end_date: Union[null, null]

formatdate

page: Optional[int]

Which 'page' of paginated results to return.

minimum1

per_page: Optional[int]

Number of items returned per page

minimum1

maximum200

ReturnsExpand Collapse

class BillingListInsightsResponse: …

current_page: int

Current page number

data_points: List[DataPoint]

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[str]

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

group_description: Optional[str]

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

region: Optional[str]

Region where the usage occurred

sku: Optional[str]

Unique SKU identifier for the billed resource

start_date: Optional[date]

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

formatdate

total_amount: Optional[str]

Total amount for this data point in USD

usage_team_urn: Optional[str]

URN of the team that incurred the usage

total_items: int

Total number of items available across all pages

total_pages: int

Total number of pages available

List Billing Insights

from datetime import date
from gradient import Gradient

client = Gradient(
    access_token="My Access Token",
)
response = client.billing.list_insights(
    end_date=date.fromisoformat("2025-01-31"),
    account_urn="do:team:12345678-1234-1234-1234-123456789012",
    start_date=date.fromisoformat("2025-01-01"),
)
print(response.current_page)

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