Context graph

Children of a context graph box

One level of what the tenant runs and pays for as boxes, for a window of up to 90 days (default the last 7 days). Without parent it returns the top-level boxes (accounts and groups, plus a group per provider and kind for boxes that sit in none) with the box-to-box links, coverage, tray, start_here and known_gaps; with parent it returns the children of that box, highest cost first with the entity id as tiebreak (children that show an allocated cost, such as namespaces and workloads, are ranked by that cost), at most group_limit at a time (CONTEXT_GRAPH_CHILD_LIMIT; CONTEXT_GRAPH_TOP_LEVEL_LIMIT without parent), and parent is that box with its total cost. children_total counts every child, including children with no cost; remainder is how many children are not shown after this page and what they cost together. Page on with next_cursor passed as cursor (it costs the same at any depth) or, for the first pages only, group_offset (at most CONTEXT_GRAPH_MAX_OFFSET); cursor and group_offset cannot be combined. include pins a box: pinned_id is set when it is a box in the window and pinned_ancestors lists the boxes above it from the top, so a client opens each level with parent set to the ancestor and include set to the next id on the path; the pinned box leads nodes only when its direct parent is the requested parent (or it is a top-level box and parent is absent) and it never appears twice in a sequence. An include or parent that is not a box in the window is a 400. Money is rounded to cents and an amount under half a cent is 0. period last_7d, last_30d and month_to_date are served from totals rebuilt in the background; their window is the one the last rebuild covered. For a custom or calendar_month window, or with a filter, every amount (the box total, its children, the remainder and the links) is exact for that window and filter; only the order of the children of a box with more than CONTEXT_GRAPH_EXACT_CHILD_THRESHOLD children is taken from the nearest rebuilt period. Unfiltered box totals come from daily totals kept for 92 days. A window older than that or ending after the last rebuild, and every filtered request on such a box, sums the bill instead and is slower. With a filter the remainder of such a box also holds the box’s own cost lines. With filter only boxes with matching cost rows are listed. Boxes with more than 2000 boxes inside show their cost, refs, details, signals other than idle and meters other than billed usage, but no breakdown, basis_parts, idle_share, has_infrastructure or billed usage meters; the others carry typed references (refs, primary), details, typed signals, meters (including bill usage per dimension with its cost and, for a host running the CostGraph agent, its hourly price), breakdown shares and basis_parts, idle_share and cluster. Billed and allocated costs are separate layers and never added together. links are the connections touching the boxes of the page. Both ends of a link are boxes the client has: a nodes entry, parent, a box above parent, a top-level box, or a child of a box listed in open. The end that is not shown stands for the nearest such box above the real far entity, and counts, bytes and cost are summed per ends, means and source. At most 3000 links are returned, the most traffic first, and links_truncated says when more exist. With scope=network the response is the whole network: every box that is an end of a network, NAT, forwarding or call link, the boxes above them, every cluster and the boxes above the included box, in one response with all links between them and no paging; parent, group_offset and cursor are not accepted. coverage.bill_only is true when the tenant has only a bill: no flow tracing, no network access granted and no agent reporting. A 503 with code context_graph_building and retry_after_seconds (also sent as Retry-After) means the totals of the tenant are not built yet.

GET

api

tenant

context-graph

children

Children of a context graph box

curl --request GET \
  --url https://api.costgraph.ai/api/v1/tenant/context-graph/children \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.costgraph.ai/api/v1/tenant/context-graph/children', 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/context-graph/children",
  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>"
  ],
]);

$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/context-graph/children"

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

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.costgraph.ai/api/v1/tenant/context-graph/children")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

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

{
  "message": "some message",
  "status": "success",
  "data": {
    "children_total": 123,
    "coverage": {
      "bill_only": true,
      "flow_tracing": true,
      "network_inventory": [
        {
          "connection_id": "<string>",
          "projects": [
            {
              "project": "<string>",
              "status": "granted"
            }
          ],
          "provider": "aws",
          "status": "granted",
          "template_url": "<string>"
        }
      ],
      "private_bytes_resolved": 123,
      "private_bytes_total": 123
    },
    "known_gaps": [
      {
        "bytes": 123,
        "code": "no_network_inventory",
        "entity_ids": [
          "<string>"
        ],
        "provider": "<string>"
      }
    ],
    "links": [
      {
        "a": "<string>",
        "b": "<string>",
        "bytes": 123,
        "cost": 123,
        "count": 123,
        "direction": "in",
        "id": "<string>",
        "means": "runs_on",
        "nat_share": 123,
        "port": 123,
        "source": "inventory",
        "write_share": 123
      }
    ],
    "links_truncated": true,
    "next_cursor": "<string>",
    "nodes": [
      {
        "basis": "billed",
        "basis_parts": [
          "nodes"
        ],
        "breakdown_allocated": [
          {
            "cost": 123,
            "estimate": true,
            "key": "<string>",
            "share": 123
          }
        ],
        "breakdown_billed": [
          {
            "cost": 123,
            "estimate": true,
            "key": "<string>",
            "share": 123
          }
        ],
        "child_count": 123,
        "cluster": "<string>",
        "cost": 123,
        "filter_match": "direct",
        "flavour": "eks",
        "gpu_model": "<string>",
        "group": "service",
        "has_infrastructure": true,
        "id": "<string>",
        "idle_share": 123,
        "instance_type": "<string>",
        "kind": "<string>",
        "meters": [
          {
            "amortization_months": 123,
            "cost": 123,
            "key": "cpu_cores",
            "list_price": 123,
            "price_source": "catalog",
            "provisioned": 123,
            "unit": "<string>",
            "value": 123
          }
        ],
        "name": "<string>",
        "open": true,
        "parent_id": "<string>",
        "path": [
          "<string>"
        ],
        "primary": "node",
        "provider": "<string>",
        "provider_name": "<string>",
        "refs": {
          "bill_resource_id": "<string>",
          "cluster_id": "<string>",
          "gpu_uuids": [
            "<string>"
          ],
          "network_endpoint_id": "<string>",
          "node_id": "<string>",
          "provider": "<string>",
          "provider_connected": true,
          "pv_resource_id": "<string>",
          "pvc_resource_id": "<string>",
          "vm_host_id": "<string>",
          "workload_resource_id": "<string>"
        },
        "signals": [
          {
            "actions": [
              "<string>"
            ],
            "anomaly_id": "<string>",
            "anomaly_type": "<string>",
            "code": "unnamed_private_traffic",
            "containers": [
              "<string>"
            ],
            "count": 123,
            "description": "<string>",
            "idle": true,
            "idle_cost": 123,
            "idle_share": 123,
            "kind": "anomaly",
            "recommended_instance_type": "<string>",
            "savings_currency": "<string>",
            "savings_monthly": 123,
            "target": "node",
            "target_provider": "<string>",
            "target_service": "<string>",
            "title": "<string>"
          }
        ],
        "version": "<string>"
      }
    ],
    "parent": {
      "basis": "billed",
      "basis_parts": [
        "nodes"
      ],
      "breakdown_allocated": [
        {
          "cost": 123,
          "estimate": true,
          "key": "<string>",
          "share": 123
        }
      ],
      "breakdown_billed": [
        {
          "cost": 123,
          "estimate": true,
          "key": "<string>",
          "share": 123
        }
      ],
      "child_count": 123,
      "cluster": "<string>",
      "cost": 123,
      "filter_match": "direct",
      "flavour": "eks",
      "gpu_model": "<string>",
      "group": "service",
      "has_infrastructure": true,
      "id": "<string>",
      "idle_share": 123,
      "instance_type": "<string>",
      "kind": "<string>",
      "meters": [
        {
          "amortization_months": 123,
          "cost": 123,
          "key": "cpu_cores",
          "list_price": 123,
          "price_source": "catalog",
          "provisioned": 123,
          "unit": "<string>",
          "value": 123
        }
      ],
      "name": "<string>",
      "open": true,
      "parent_id": "<string>",
      "path": [
        "<string>"
      ],
      "primary": "node",
      "provider": "<string>",
      "provider_name": "<string>",
      "refs": {
        "bill_resource_id": "<string>",
        "cluster_id": "<string>",
        "gpu_uuids": [
          "<string>"
        ],
        "network_endpoint_id": "<string>",
        "node_id": "<string>",
        "provider": "<string>",
        "provider_connected": true,
        "pv_resource_id": "<string>",
        "pvc_resource_id": "<string>",
        "vm_host_id": "<string>",
        "workload_resource_id": "<string>"
      },
      "signals": [
        {
          "actions": [
            "<string>"
          ],
          "anomaly_id": "<string>",
          "anomaly_type": "<string>",
          "code": "unnamed_private_traffic",
          "containers": [
            "<string>"
          ],
          "count": 123,
          "description": "<string>",
          "idle": true,
          "idle_cost": 123,
          "idle_share": 123,
          "kind": "anomaly",
          "recommended_instance_type": "<string>",
          "savings_currency": "<string>",
          "savings_monthly": 123,
          "target": "node",
          "target_provider": "<string>",
          "target_service": "<string>",
          "title": "<string>"
        }
      ],
      "version": "<string>"
    },
    "pinned_ancestors": [
      "<string>"
    ],
    "pinned_id": "<string>",
    "remainder": {
      "cost": 123,
      "count": 123
    },
    "start_here": [
      {
        "anomaly_id": "<string>",
        "code": "idle_capacity",
        "cost": 123,
        "entity_id": "<string>",
        "period": "window",
        "share": 123
      }
    ],
    "tray": {
      "billed": [
        {
          "cost": 123,
          "provider": "<string>"
        }
      ],
      "seen": [
        {
          "bytes": 123,
          "connections": 123,
          "provider": "<string>"
        }
      ]
    },
    "window": {
      "end": "<string>",
      "filters": {},
      "start": "<string>"
    }
  }
}

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

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

{
  "code": "context_graph_building",
  "message": "The context graph is being built for this tenant",
  "retry_after_seconds": 123,
  "status": "error"
}

Authorizations

Authorization

string

header

required

Enter "Bearer {token}"

Headers

X-CostGraph-Tenant-ID

string

Tenant ID

Query Parameters

parent

string

Box whose children to return; omit for the top-level boxes

include

string

Box to pin at the top of its level and return the ancestors of

open

string[]

Boxes the client has expanded (repeat the parameter or comma-separated); only decides which box a link to a box that is not shown points at

period

enum<string>

Window; defaults to last_7d

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

scope

enum<string>

Return the whole network graph in one response; only network is accepted

Available options:

network

filter

string[]

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

group_limit

integer

Children per page; defaults to and is at most the server limit

group_offset

integer

Children to skip, at most the server limit; cannot be combined with cursor

cursor

string

next_cursor of the previous page

Response

message

string

required

Example:

"some message"

status

string

required

Example:

"success"

data

object

Show child attributes

Children of a context graph box

curl --request GET \
  --url https://api.costgraph.ai/api/v1/tenant/context-graph/children \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.costgraph.ai/api/v1/tenant/context-graph/children', 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/context-graph/children",
  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>"
  ],
]);

$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/context-graph/children"

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

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.costgraph.ai/api/v1/tenant/context-graph/children")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

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

{
  "message": "some message",
  "status": "success",
  "data": {
    "children_total": 123,
    "coverage": {
      "bill_only": true,
      "flow_tracing": true,
      "network_inventory": [
        {
          "connection_id": "<string>",
          "projects": [
            {
              "project": "<string>",
              "status": "granted"
            }
          ],
          "provider": "aws",
          "status": "granted",
          "template_url": "<string>"
        }
      ],
      "private_bytes_resolved": 123,
      "private_bytes_total": 123
    },
    "known_gaps": [
      {
        "bytes": 123,
        "code": "no_network_inventory",
        "entity_ids": [
          "<string>"
        ],
        "provider": "<string>"
      }
    ],
    "links": [
      {
        "a": "<string>",
        "b": "<string>",
        "bytes": 123,
        "cost": 123,
        "count": 123,
        "direction": "in",
        "id": "<string>",
        "means": "runs_on",
        "nat_share": 123,
        "port": 123,
        "source": "inventory",
        "write_share": 123
      }
    ],
    "links_truncated": true,
    "next_cursor": "<string>",
    "nodes": [
      {
        "basis": "billed",
        "basis_parts": [
          "nodes"
        ],
        "breakdown_allocated": [
          {
            "cost": 123,
            "estimate": true,
            "key": "<string>",
            "share": 123
          }
        ],
        "breakdown_billed": [
          {
            "cost": 123,
            "estimate": true,
            "key": "<string>",
            "share": 123
          }
        ],
        "child_count": 123,
        "cluster": "<string>",
        "cost": 123,
        "filter_match": "direct",
        "flavour": "eks",
        "gpu_model": "<string>",
        "group": "service",
        "has_infrastructure": true,
        "id": "<string>",
        "idle_share": 123,
        "instance_type": "<string>",
        "kind": "<string>",
        "meters": [
          {
            "amortization_months": 123,
            "cost": 123,
            "key": "cpu_cores",
            "list_price": 123,
            "price_source": "catalog",
            "provisioned": 123,
            "unit": "<string>",
            "value": 123
          }
        ],
        "name": "<string>",
        "open": true,
        "parent_id": "<string>",
        "path": [
          "<string>"
        ],
        "primary": "node",
        "provider": "<string>",
        "provider_name": "<string>",
        "refs": {
          "bill_resource_id": "<string>",
          "cluster_id": "<string>",
          "gpu_uuids": [
            "<string>"
          ],
          "network_endpoint_id": "<string>",
          "node_id": "<string>",
          "provider": "<string>",
          "provider_connected": true,
          "pv_resource_id": "<string>",
          "pvc_resource_id": "<string>",
          "vm_host_id": "<string>",
          "workload_resource_id": "<string>"
        },
        "signals": [
          {
            "actions": [
              "<string>"
            ],
            "anomaly_id": "<string>",
            "anomaly_type": "<string>",
            "code": "unnamed_private_traffic",
            "containers": [
              "<string>"
            ],
            "count": 123,
            "description": "<string>",
            "idle": true,
            "idle_cost": 123,
            "idle_share": 123,
            "kind": "anomaly",
            "recommended_instance_type": "<string>",
            "savings_currency": "<string>",
            "savings_monthly": 123,
            "target": "node",
            "target_provider": "<string>",
            "target_service": "<string>",
            "title": "<string>"
          }
        ],
        "version": "<string>"
      }
    ],
    "parent": {
      "basis": "billed",
      "basis_parts": [
        "nodes"
      ],
      "breakdown_allocated": [
        {
          "cost": 123,
          "estimate": true,
          "key": "<string>",
          "share": 123
        }
      ],
      "breakdown_billed": [
        {
          "cost": 123,
          "estimate": true,
          "key": "<string>",
          "share": 123
        }
      ],
      "child_count": 123,
      "cluster": "<string>",
      "cost": 123,
      "filter_match": "direct",
      "flavour": "eks",
      "gpu_model": "<string>",
      "group": "service",
      "has_infrastructure": true,
      "id": "<string>",
      "idle_share": 123,
      "instance_type": "<string>",
      "kind": "<string>",
      "meters": [
        {
          "amortization_months": 123,
          "cost": 123,
          "key": "cpu_cores",
          "list_price": 123,
          "price_source": "catalog",
          "provisioned": 123,
          "unit": "<string>",
          "value": 123
        }
      ],
      "name": "<string>",
      "open": true,
      "parent_id": "<string>",
      "path": [
        "<string>"
      ],
      "primary": "node",
      "provider": "<string>",
      "provider_name": "<string>",
      "refs": {
        "bill_resource_id": "<string>",
        "cluster_id": "<string>",
        "gpu_uuids": [
          "<string>"
        ],
        "network_endpoint_id": "<string>",
        "node_id": "<string>",
        "provider": "<string>",
        "provider_connected": true,
        "pv_resource_id": "<string>",
        "pvc_resource_id": "<string>",
        "vm_host_id": "<string>",
        "workload_resource_id": "<string>"
      },
      "signals": [
        {
          "actions": [
            "<string>"
          ],
          "anomaly_id": "<string>",
          "anomaly_type": "<string>",
          "code": "unnamed_private_traffic",
          "containers": [
            "<string>"
          ],
          "count": 123,
          "description": "<string>",
          "idle": true,
          "idle_cost": 123,
          "idle_share": 123,
          "kind": "anomaly",
          "recommended_instance_type": "<string>",
          "savings_currency": "<string>",
          "savings_monthly": 123,
          "target": "node",
          "target_provider": "<string>",
          "target_service": "<string>",
          "title": "<string>"
        }
      ],
      "version": "<string>"
    },
    "pinned_ancestors": [
      "<string>"
    ],
    "pinned_id": "<string>",
    "remainder": {
      "cost": 123,
      "count": 123
    },
    "start_here": [
      {
        "anomaly_id": "<string>",
        "code": "idle_capacity",
        "cost": 123,
        "entity_id": "<string>",
        "period": "window",
        "share": 123
      }
    ],
    "tray": {
      "billed": [
        {
          "cost": 123,
          "provider": "<string>"
        }
      ],
      "seen": [
        {
          "bytes": 123,
          "connections": 123,
          "provider": "<string>"
        }
      ]
    },
    "window": {
      "end": "<string>",
      "filters": {},
      "start": "<string>"
    }
  }
}

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

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

{
  "code": "context_graph_building",
  "message": "The context graph is being built for this tenant",
  "retry_after_seconds": 123,
  "status": "error"
}

Getting started

Endpoints

Children of a context graph box

Authorizations

Headers

Query Parameters

Response