List Billing Insights

client.Billing.ListInsights(ctx, accountUrn, startDate, endDate, query) (*BillingListInsightsResponse, error)

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

accountUrn string

startDate Time

formatdate

endDate Time

formatdate

query BillingListInsightsParams

Page param.Field[int64]optional

Which 'page' of paginated results to return.

minimum1

PerPage param.Field[int64]optional

Number of items returned per page

minimum1

maximum200

ReturnsExpand Collapse

type BillingListInsightsResponse struct{…}

CurrentPage int64

Current page number

DataPoints []BillingListInsightsResponseDataPoint

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 stringoptional

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

GroupDescription stringoptional

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

Region stringoptional

Region where the usage occurred

SKU stringoptional

Unique SKU identifier for the billed resource

StartDate Timeoptional

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

formatdate

TotalAmount stringoptional

Total amount for this data point in USD

UsageTeamUrn stringoptional

URN of the team that incurred the usage

TotalItems int64

Total number of items available across all pages

TotalPages int64

Total number of pages available

List Billing Insights

package main

import (
  "context"
  "fmt"
  "time"

  "github.com/stainless-sdks/-go"
  "github.com/stainless-sdks/-go/option"
)

func main() {
  client := gradient.NewClient(
    option.WithAccessToken("My Access Token"),
  )
  response, err := client.Billing.ListInsights(
    context.TODO(),
    "do:team:12345678-1234-1234-1234-123456789012",
    time.Now(),
    time.Now(),
    gradient.BillingListInsightsParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.CurrentPage)
}

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