Cost

Cost per customer

Spend per customer for a period, where a customer is a value of the tenant’s customer dimension (or of the dimension query parameter, to preview another one). Each customer carries direct spend, the shared spend it receives when the dimension is a tag key with split rules (sharedSplit says whether any applied), its total, the previous period’s total, its change, share and a daily sparkline. Totals give the customer count, average and median cost per customer and the spend no customer accounts for (unallocated), so customers plus unallocated add up to the total. trend gives cost per customer per day or month. Amounts are gross (credits left out), in the reporting currency; spend with no exchange rate is left out and listed under unconverted. Layers are never mixed. dimension is null and every list empty when no customer dimension is set. With format=csv or format=xlsx the response is a file with one row per customer, the unallocated row and a total row.

GET

api

tenant

cost

customers

Cost per customer

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

import requests

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

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/customers', 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/customers",
  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/customers"

	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/customers")
  .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/customers")

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": {
    "customers": [
      {
        "changeAmount": 123,
        "changePct": 123,
        "current": 123,
        "direct": 123,
        "key": "<string>",
        "label": "<string>",
        "previous": 123,
        "share": 123,
        "shared": 123,
        "sparkline": [
          {
            "cost": 123,
            "day": "<string>"
          }
        ]
      }
    ],
    "days": [
      "<string>"
    ],
    "dimension": "<string>",
    "granularity": "<string>",
    "layer": "<string>",
    "previousComparable": true,
    "reportingCurrency": "<string>",
    "sharedSplit": true,
    "totals": {
      "averageCostPerCustomer": 123,
      "customers": 123,
      "medianCostPerCustomer": 123,
      "previous": 123,
      "previousAverageCostPerCustomer": 123,
      "previousCustomers": 123,
      "previousUnallocated": 123,
      "total": 123,
      "unallocated": 123,
      "unallocatedShare": 123
    },
    "trend": [
      {
        "bucket": "<string>",
        "costPerCustomer": 123,
        "customerCost": 123,
        "customers": 123,
        "unallocated": 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

dimension

string

sub_account, tag: or extension:; defaults to the tenant's customer dimension

layer

enum<string>

Cost layer; defaults to billed

Available options:

billed,

allocation

granularity

enum<string>

Trend bucket; defaults to day

Available options:

day,

month

limit

integer

Maximum customers listed, largest spend first; defaults to 100

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; defaults to the currency most of the period's spend was billed in

filter

string[]

Repeated key:value dimension filter, same keys and modifiers as /cost/query

format

enum<string>

Response format; defaults to json

Available options:

json,

csv,

xlsx

Response

message

string

required

Example:

"some message"

status

string

required

Example:

"success"

data

object

Show child attributes

Cost per customer

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

import requests

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

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/customers', 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/customers",
  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/customers"

	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/customers")
  .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/customers")

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": {
    "customers": [
      {
        "changeAmount": 123,
        "changePct": 123,
        "current": 123,
        "direct": 123,
        "key": "<string>",
        "label": "<string>",
        "previous": 123,
        "share": 123,
        "shared": 123,
        "sparkline": [
          {
            "cost": 123,
            "day": "<string>"
          }
        ]
      }
    ],
    "days": [
      "<string>"
    ],
    "dimension": "<string>",
    "granularity": "<string>",
    "layer": "<string>",
    "previousComparable": true,
    "reportingCurrency": "<string>",
    "sharedSplit": true,
    "totals": {
      "averageCostPerCustomer": 123,
      "customers": 123,
      "medianCostPerCustomer": 123,
      "previous": 123,
      "previousAverageCostPerCustomer": 123,
      "previousCustomers": 123,
      "previousUnallocated": 123,
      "total": 123,
      "unallocated": 123,
      "unallocatedShare": 123
    },
    "trend": [
      {
        "bucket": "<string>",
        "costPerCustomer": 123,
        "customerCost": 123,
        "customers": 123,
        "unallocated": 123
      }
    ],
    "unconverted": [
      {
        "currency": "<string>",
        "nativeTotal": 123
      }
    ]
  }
}

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

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

Getting started

Endpoints

Cost per customer

Authorizations

Headers

Query Parameters

Response