Cost query

GET

api

tenant

cost

query

Cost query

curl --request GET \
  --url https://api.costgraph.ai/api/v1/tenant/cost/query \
  --header 'Authorization: <api-key>' \
  --header 'X-CostGraph-Tenant-ID: <x-costgraph-tenant-id>'

import requests

url = "https://api.costgraph.ai/api/v1/tenant/cost/query"

headers = {
    "X-CostGraph-Tenant-ID": "<x-costgraph-tenant-id>",
    "Authorization": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-CostGraph-Tenant-ID': '<x-costgraph-tenant-id>', Authorization: '<api-key>'}
};

fetch('https://api.costgraph.ai/api/v1/tenant/cost/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.costgraph.ai/api/v1/tenant/cost/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "X-CostGraph-Tenant-ID: <x-costgraph-tenant-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.costgraph.ai/api/v1/tenant/cost/query"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-CostGraph-Tenant-ID", "<x-costgraph-tenant-id>")
	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.costgraph.ai/api/v1/tenant/cost/query")
  .header("X-CostGraph-Tenant-ID", "<x-costgraph-tenant-id>")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.costgraph.ai/api/v1/tenant/cost/query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-CostGraph-Tenant-ID"] = '<x-costgraph-tenant-id>'
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "message": "some message",
  "status": "success",
  "data": {
    "byCurrency": [
      {
        "convertedTotal": 123,
        "currency": "<string>",
        "effectiveRate": 123,
        "latestRateDate": "<string>",
        "nativeTotal": 123,
        "nearestRateUsed": true
      }
    ],
    "categoryTotals": [
      {
        "chargeCategory": "<string>",
        "current": 123,
        "previous": 123
      }
    ],
    "days": [
      "<string>"
    ],
    "facets": {
      "extensions": {},
      "provider": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "region": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "resource_type": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "service_category": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "sub_account": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "tags": {},
      "truncated": [
        "<string>"
      ]
    },
    "groups": [
      {
        "billedCost": 123,
        "byCurrency": [
          {
            "convertedTotal": 123,
            "currency": "<string>",
            "nativeTotal": 123
          }
        ],
        "changeAmount": 123,
        "changePct": 123,
        "chargeCategory": "<string>",
        "children": "<array>",
        "contractedCost": 123,
        "count": 123,
        "current": 123,
        "dimension": "<string>",
        "key": "<string>",
        "label": "<string>",
        "listCost": 123,
        "other": true,
        "possibleSavings": 123,
        "previous": 123,
        "pricingCategory": "<string>",
        "resourceId": "<string>",
        "resourceType": "<string>",
        "service": "<string>",
        "share": 123,
        "skuMeter": "<string>",
        "subAccountCount": 123,
        "subAccountOther": {
          "billedCost": 123,
          "byCurrency": [
            {
              "convertedTotal": 123,
              "currency": "<string>",
              "nativeTotal": 123
            }
          ],
          "changeAmount": 123,
          "changePct": 123,
          "chargeCategory": "<string>",
          "contractedCost": 123,
          "count": 123,
          "current": 123,
          "id": "<string>",
          "listCost": 123,
          "name": "<string>",
          "previous": 123,
          "pricingCategory": "<string>",
          "service": "<string>",
          "share": 123,
          "type": "<string>",
          "unitPrice": 123,
          "unitPriceUnit": "<string>",
          "usageQuantity": 123,
          "usageUnit": "<string>"
        },
        "subAccountUnassigned": {
          "billedCost": 123,
          "byCurrency": [
            {
              "convertedTotal": 123,
              "currency": "<string>",
              "nativeTotal": 123
            }
          ],
          "changeAmount": 123,
          "changePct": 123,
          "chargeCategory": "<string>",
          "contractedCost": 123,
          "count": 123,
          "current": 123,
          "id": "<string>",
          "listCost": 123,
          "name": "<string>",
          "previous": 123,
          "pricingCategory": "<string>",
          "service": "<string>",
          "share": 123,
          "type": "<string>",
          "unitPrice": 123,
          "unitPriceUnit": "<string>",
          "usageQuantity": 123,
          "usageUnit": "<string>"
        },
        "subAccounts": [
          {
            "billedCost": 123,
            "byCurrency": [
              {
                "convertedTotal": 123,
                "currency": "<string>",
                "nativeTotal": 123
              }
            ],
            "changeAmount": 123,
            "changePct": 123,
            "chargeCategory": "<string>",
            "contractedCost": 123,
            "count": 123,
            "current": 123,
            "id": "<string>",
            "listCost": 123,
            "name": "<string>",
            "previous": 123,
            "pricingCategory": "<string>",
            "service": "<string>",
            "share": 123,
            "type": "<string>",
            "unitPrice": 123,
            "unitPriceUnit": "<string>",
            "usageQuantity": 123,
            "usageUnit": "<string>"
          }
        ],
        "unallocated": true,
        "unitPrice": 123,
        "unitPriceUnit": "<string>",
        "usageQuantity": 123,
        "usageUnit": "<string>"
      }
    ],
    "netCurrent": 123,
    "netPrevious": 123,
    "previousComparable": true,
    "reportingCurrency": "<string>",
    "series": [
      {
        "cost": 123,
        "day": "<string>",
        "stack": "<string>"
      }
    ],
    "stackLabels": {},
    "totals": {
      "changeAmount": 123,
      "changePct": 123,
      "credits": 123,
      "creditsCoverPct": 123,
      "creditsPrevious": 123,
      "current": 123,
      "dailyAverage": 123,
      "monthToDate": 123,
      "monthlyPace": 123,
      "net": 123,
      "netPrevious": 123,
      "previous": 123,
      "searchSharePct": 123
    },
    "unconverted": [
      {
        "currency": "<string>",
        "nativeTotal": 123
      }
    ]
  }
}

{
  "message": "some message",
  "status": "error"
}

{
  "message": "some message",
  "status": "error"
}

Authorizations

Authorization

string

header

required

Enter "Bearer {token}"

Headers

X-CostGraph-Tenant-ID

string

required

Tenant ID

Query Parameters

period

enum<string>

Cost period; defaults to month_to_date

Available options:

month_to_date,

last_7d,

last_30d,

calendar_month,

custom

month

string

Closed calendar month in YYYY-MM format; required when period=calendar_month

start

string

Window start in RFC3339 format; required when period=custom

end

string

Window end in RFC3339 format; required when period=custom

reporting_currency

string

ISO 4217 code to express every amount in, converted at each day's exchange rate; defaults to the currency most of the selected period's spend was billed in, or USD when none dominates

group_by

string

required

Ordered, comma-separated dimensions to group by; nested into a tree (e.g. provider,region,resource_type). Fixed dimensions: provider, resource_type, service_category, service_subcategory, service, region, availability_zone, resource, sku_id, sku_meter, charge_category, charge_description, pricing_category, pricing_unit, usage_unit, billing_account_id, sub_account, sub_account_type, invoice_id, invoice_issuer, publisher, currency. Tag and virtual-tag keys are also accepted as tag:, and provider extension keys as extension:; those keys are per-tenant or per-provider so they are not enumerable here

stack_by

string

Dimension to stack the time series by; accepts any dimension group_by accepts, including tag: and extension:

layer

enum<string>

Cost layer; defaults to billed. ci returns CI runner job rows, including each job's share of a vendor bill.

Available options:

billed,

allocation,

ci

group_limit

integer

Maximum groups returned per level of the group tree; defaults to 100. Groups beyond the limit are combined into one final entry per level, marked other=true and carrying the folded group count

group_offset

integer

Number of top-level groups to skip, for paging past group_limit; deeper levels are not paged. The trailing other entry counts the groups left after this page

string

Case-insensitive text matched against the values and names of the grouped dimensions; totals, groups and series cover only matching rows, and totals.searchSharePct gives their share of the unsearched total

format

enum<string>

Response format; defaults to json. csv and xlsx download the full group table as a file

Available options:

json,

csv,

xlsx

include_sub_accounts

boolean

Break every group down by sub-account, returning the top spenders plus a rollup of the rest and, where the group is only partly attributed, the unassigned remainder

filter

string[]

Repeated key:value dimension filter, repeat a key to match any of its values, e.g. filter=provider:aws&filter=provider:gcp. Keys are the same dimensions group_by accepts: provider, resource_type, service_category, service_subcategory, service, region, availability_zone, resource, sku_id, sku_meter, charge_category, charge_description, pricing_category, pricing_unit, usage_unit, billing_account_id, sub_account, sub_account_type, invoice_id, invoice_issuer, publisher, currency, plus per-tenant tag and virtual-tag keys as filter=tag:: and provider extension keys as filter=extension::. Prefix a dimension with has: for rows where it resolves at all, e.g. filter=has:tag:owner, filter=has:extension:x_ProjectId or filter=has:region. Prefix a dimension with no: for rows where it does not resolve, e.g. filter=no:tag:owner or filter=no:region. Prefix a dimension with not: to drop the given values, keeping rows where it does not resolve, repeat it to drop several, e.g. filter=not:provider:aws&filter=not:provider:gcp or filter=not:tag:team:platform; it combines with a plain filter on the same dimension. A filter_= query parameter is equivalent

Response

message

string

required

Example:

"some message"

status

string

required

Example:

"success"

data

object

Show child attributes

Cost query

curl --request GET \
  --url https://api.costgraph.ai/api/v1/tenant/cost/query \
  --header 'Authorization: <api-key>' \
  --header 'X-CostGraph-Tenant-ID: <x-costgraph-tenant-id>'

import requests

url = "https://api.costgraph.ai/api/v1/tenant/cost/query"

headers = {
    "X-CostGraph-Tenant-ID": "<x-costgraph-tenant-id>",
    "Authorization": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-CostGraph-Tenant-ID': '<x-costgraph-tenant-id>', Authorization: '<api-key>'}
};

fetch('https://api.costgraph.ai/api/v1/tenant/cost/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.costgraph.ai/api/v1/tenant/cost/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "X-CostGraph-Tenant-ID: <x-costgraph-tenant-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.costgraph.ai/api/v1/tenant/cost/query"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-CostGraph-Tenant-ID", "<x-costgraph-tenant-id>")
	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.costgraph.ai/api/v1/tenant/cost/query")
  .header("X-CostGraph-Tenant-ID", "<x-costgraph-tenant-id>")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.costgraph.ai/api/v1/tenant/cost/query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-CostGraph-Tenant-ID"] = '<x-costgraph-tenant-id>'
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "message": "some message",
  "status": "success",
  "data": {
    "byCurrency": [
      {
        "convertedTotal": 123,
        "currency": "<string>",
        "effectiveRate": 123,
        "latestRateDate": "<string>",
        "nativeTotal": 123,
        "nearestRateUsed": true
      }
    ],
    "categoryTotals": [
      {
        "chargeCategory": "<string>",
        "current": 123,
        "previous": 123
      }
    ],
    "days": [
      "<string>"
    ],
    "facets": {
      "extensions": {},
      "provider": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "region": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "resource_type": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "service_category": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "sub_account": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "tags": {},
      "truncated": [
        "<string>"
      ]
    },
    "groups": [
      {
        "billedCost": 123,
        "byCurrency": [
          {
            "convertedTotal": 123,
            "currency": "<string>",
            "nativeTotal": 123
          }
        ],
        "changeAmount": 123,
        "changePct": 123,
        "chargeCategory": "<string>",
        "children": "<array>",
        "contractedCost": 123,
        "count": 123,
        "current": 123,
        "dimension": "<string>",
        "key": "<string>",
        "label": "<string>",
        "listCost": 123,
        "other": true,
        "possibleSavings": 123,
        "previous": 123,
        "pricingCategory": "<string>",
        "resourceId": "<string>",
        "resourceType": "<string>",
        "service": "<string>",
        "share": 123,
        "skuMeter": "<string>",
        "subAccountCount": 123,
        "subAccountOther": {
          "billedCost": 123,
          "byCurrency": [
            {
              "convertedTotal": 123,
              "currency": "<string>",
              "nativeTotal": 123
            }
          ],
          "changeAmount": 123,
          "changePct": 123,
          "chargeCategory": "<string>",
          "contractedCost": 123,
          "count": 123,
          "current": 123,
          "id": "<string>",
          "listCost": 123,
          "name": "<string>",
          "previous": 123,
          "pricingCategory": "<string>",
          "service": "<string>",
          "share": 123,
          "type": "<string>",
          "unitPrice": 123,
          "unitPriceUnit": "<string>",
          "usageQuantity": 123,
          "usageUnit": "<string>"
        },
        "subAccountUnassigned": {
          "billedCost": 123,
          "byCurrency": [
            {
              "convertedTotal": 123,
              "currency": "<string>",
              "nativeTotal": 123
            }
          ],
          "changeAmount": 123,
          "changePct": 123,
          "chargeCategory": "<string>",
          "contractedCost": 123,
          "count": 123,
          "current": 123,
          "id": "<string>",
          "listCost": 123,
          "name": "<string>",
          "previous": 123,
          "pricingCategory": "<string>",
          "service": "<string>",
          "share": 123,
          "type": "<string>",
          "unitPrice": 123,
          "unitPriceUnit": "<string>",
          "usageQuantity": 123,
          "usageUnit": "<string>"
        },
        "subAccounts": [
          {
            "billedCost": 123,
            "byCurrency": [
              {
                "convertedTotal": 123,
                "currency": "<string>",
                "nativeTotal": 123
              }
            ],
            "changeAmount": 123,
            "changePct": 123,
            "chargeCategory": "<string>",
            "contractedCost": 123,
            "count": 123,
            "current": 123,
            "id": "<string>",
            "listCost": 123,
            "name": "<string>",
            "previous": 123,
            "pricingCategory": "<string>",
            "service": "<string>",
            "share": 123,
            "type": "<string>",
            "unitPrice": 123,
            "unitPriceUnit": "<string>",
            "usageQuantity": 123,
            "usageUnit": "<string>"
          }
        ],
        "unallocated": true,
        "unitPrice": 123,
        "unitPriceUnit": "<string>",
        "usageQuantity": 123,
        "usageUnit": "<string>"
      }
    ],
    "netCurrent": 123,
    "netPrevious": 123,
    "previousComparable": true,
    "reportingCurrency": "<string>",
    "series": [
      {
        "cost": 123,
        "day": "<string>",
        "stack": "<string>"
      }
    ],
    "stackLabels": {},
    "totals": {
      "changeAmount": 123,
      "changePct": 123,
      "credits": 123,
      "creditsCoverPct": 123,
      "creditsPrevious": 123,
      "current": 123,
      "dailyAverage": 123,
      "monthToDate": 123,
      "monthlyPace": 123,
      "net": 123,
      "netPrevious": 123,
      "previous": 123,
      "searchSharePct": 123
    },
    "unconverted": [
      {
        "currency": "<string>",
        "nativeTotal": 123
      }
    ]
  }
}

{
  "message": "some message",
  "status": "error"
}

{
  "message": "some message",
  "status": "error"
}

Getting started

Endpoints

Authorizations

Headers

Query Parameters

Response