insights

Creates, updates, deletes, gets or lists an insights resource.

Overview

Name	insights
Type	Resource
Id	digitalocean.billing.insights

Fields

The following fields are returned by SELECT queries:

billing_insights_list

The response will be a JSON object that contains a list of billing data points under the data_points key, along with pagination metadata including total_items, total_pages, and current_page.

Name	Datatype	Description
description	string	Description of the billed resource or service as shown on an invoice item (example: droplet name (c-2-4GiB))
group_description	string	Optional invoice item group name of the billed resource or service, blank when not part an invoice item group (example: kubernetes cluster name)
region	string	Region where the usage occurred (example: nyc3)
sku	string	Unique SKU identifier for the billed resource (example: 1-DO-DROP-0109)
start_date	string (date)	Start date of the billing data point in YYYY-MM-DD format (example: 2025-01-15)
total_amount	string	Total amount for this data point in USD (example: 12.45)
usage_team_urn	string	URN of the team that incurred the usage (example: do:team:12345678-1234-1234-1234-123456789012)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
billing_insights_list	select	account_urn, start_date, end_date	per_page, page	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

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
account_urn	string	URN of the customer account, can be a team (do:team:uuid) or an organization (do:teamgroup:uuid) (example: do:team:12345678-1234-1234-1234-123456789012)
end_date	string (date)	End date for billing insights in YYYY-MM-DD format. Must be within 31 days of start_date (example: 2025-01-31)
start_date	string (date)	Start date for billing insights in YYYY-MM-DD format (example: 2025-01-01)
page	integer	Which 'page' of paginated results to return. (example: 1)
per_page	integer	Number of items returned per page (example: 2)

SELECT examples

billing_insights_list

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.

SELECT
description,
group_description,
region,
sku,
start_date,
total_amount,
usage_team_urn
FROM digitalocean.billing.insights
WHERE account_urn = '{{ account_urn }}' -- required
AND start_date = '{{ start_date }}' -- required
AND end_date = '{{ end_date }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;