For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.billing_insights.list(
    account_urn="do:team:12345678-1234-1234-1234-123456789012",
    start_date="2025-01-01",
    end_date="2025-01-31",
    per_page=20,
    page=1,
)

Description

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.

Parameters

account_urn string required

URN of the customer account, can be a team (do:team:uuid) or an organization (do:teamgroup:uuid)

start_date string required

Start date for billing insights in YYYY-MM-DD format

end_date string required

End date for billing insights in YYYY-MM-DD format. Must be within 31 days of start_date

per_page integer optional

Number of items returned per page

Min: 1

Max: 200

Default: 20

page integer optional

Which 'page' of paginated results to return.

Min: 1

Default: 1

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

insights = client.billing.list_insights(
    account_urn="do:team:12345678-1234-1234-1234-123456789012",
    start_date="2025-01-01",
    end_date="2025-01-31",
    per_page=100,
    page=1
)

Pagination

This method returns paginated results. The response includes a links.pages object with URLs for navigating between pages. To retrieve the next page, parse the next URL and pass the page parameter:

from urllib.parse import urlparse, parse_qs

resp = client.billing_insights.list(account_urn="do:team:12345678-1234-1234-1234-123456789012", start_date="2025-01-01", end_date="2025-01-31", )
pages = resp.get("links", {}).get("pages", {})

while "next" in pages:
    parsed = urlparse(pages["next"])
    page = int(parse_qs(parsed.query)["page"][0])
    resp = client.billing_insights.list(account_urn="do:team:12345678-1234-1234-1234-123456789012", start_date="2025-01-01", end_date="2025-01-31", page=page)
    pages = resp.get("links", {}).get("pages", {})

Response Example

{
  "data_points": [
    {
      "usage_team_urn": "do:team:12345678-1234-1234-1234-123456789012",
      "start_date": "2025-01-01",
      "total_amount": "0.86",
      "region": "nyc3",
      "sku": "1-DO-DROP-0109",
      "description": "droplet name (c-2-4GiB)",
      "group_description": ""
    },
    {
      "usage_team_urn": "do:team:12345678-1234-1234-1234-123456789012",
      "start_date": "2025-01-01",
      "total_amount": "2.57",
      "region": "nyc3",
      "sku": "1-KS-K8SWN-00109",
      "description": "3 nodes - 4 GB / 2 vCPU / 80 GB SSD",
      "group_description": "kubernetes cluster name"
    }
  ],
  "total_items": 2,
  "total_pages": 1,
  "current_page": 1
}

More Information

See /v2/billing/{account_urn}/insights/{start_date}/{end_date} in the API reference for additional detail on responses, headers, parameters, and more.