Retrieve Bandwidth Metrics with API calls

Overview

You can use this document to learn how to use the StackPath API system to monitor the ingress and egress bandwidth of a workload. 

---

Review available metrics 

Bandwidth metrics can be pulled for an entire stack or for an individual workload. Bandwidth is always divided by StackPath PoP locations and will have to be summed for total use.

Endpoint: https://gateway.stackpath.com/workload/v1/stacks/<stack_id>/metrics

Method: GET

Query Parameters

type (String) (Required)
Set the value as "BANDWIDTH" to pull bandwidth metrics

start_date (Datetime) (Required)
Start Date specified the beginning of the reporting period over which the call pulls metrics from. If this period is before the date of workload creation, all values will be set to zero.

The datetime string should be in the standard datetime format YYYY-MM-DDTHH:MM:ss.sssZ

end_date (Datetime) (Required)
End Date specified the end of the reporting period over which the call pulls metrics from. If this period is after the current time, a JSON response with 'message': 'Unable to get metrics at this time'. will be returned.

The datetime string should be in the standard datetime format YYYY-MM-DDTHH:MM:ss.sssZ

workload_id (String) (Optional, Default: All Workloads)
Workload ID can be pulled from the URL in the StackPath Control Panel or from the Compute API GET workloads endpoint.

granularity(String) (Optional, Default: PT5M)

The summation period of metrics between the start_date and end_date.

• PT5M - 5 minutes
• PT1H - 1 hour
• P1D - 1 Day

PoP (String) (Optional, Default: ALL)
Filter traffic metrics by StackPath Point of Presence. Pull the possible location identifiers via the StackPath API Endpoint GET Locations.

---

Obtain daily metrics by workload

API Request

Method: GET
Endpoint: https://gateway.stackpath.com/workload/v1/stacks/{stack_id}/metrics

Payload

{
 'start_date': '2019-03-23T14:54:18.442Z',
 'end_date': '2019-03-24T14:54:18.442Z',
 'wordload_id': "{stack_id}",
 'type': "BANDWIDTH",
 'granularity': 'P1D',
 }

cURL Example

curl "https://gateway.stackpath.com/workload/v1/stacks/<stack_id>/metrics?start_date=2019-03-23T14:54:18.442Z&end_date=2019-03-24T14:54:18.442Z&workload_id=<workload_id>&type=BANDWIDTH&granularity=P1D" -H "Authorization: Bearer <token>"

 

---

Obtain hourly metrics by instance

API Request

Method: GET
Endpoint: https://gateway.stackpath.com/workload/v1/stacks/{stack_id}/metrics

Payload

{
 'start_date': '2019-03-23T14:54:18.442Z',
 'end_date': '2019-03-24T14:54:18.442Z',
 'workload_id': "{stack_id}",
 'instance_name': "{instance_hostname}"
 'type': "BANDWIDTH",
 'granularity': 'PT1H',
 }

cURL Example

curl "https://gateway.stackpath.com/workload/v1/stacks/<stack_id>/metrics?start_date=2019-03-23T14:54:18.442Z&end_date=2019-03-24T14:54:18.442Z&workload_id=<workload_id>&instance_name=<instance_hostname>&type=BANDWIDTH&granularity=PT1H" -H "Authorization: Bearer <token>"

 

---

Obtain filtered metrics by PoP

API Request

Method: GET

Endpoint: https://gateway.stackpath.com/workload/v1/stacks/{stack_id}/metrics

Payload

{
 'start_date': '2019-03-23T14:54:18.442Z',
 'end_date': '2019-03-24T14:54:18.442Z',
 'workload_id': "{stack_id}",
 'type': "BANDWIDTH",
 'granularity': 'P1D',
 'pop': 'lhr02'
 }

cURL Example

curl "https://gateway.stackpath.com/workload/v1/stacks/<stack_id>/metrics?start_date=2019-03-23T14:54:18.442Z&end_date=2019-03-24T14:54:18.442Z&workload_id=<workload_id>&type=BANDWIDTH&granularity=P1D&pop=lhr02" -H "Authorization: Bearer <token>" 

Review response

Status Code: 200

{
  "status":"success",
  "data":{
    "resultType":"matrix",
    "result":[{
      "metric":{
        "__name__":"ingress_bandwidth",
        "pop":"lhr02",
        "traffic_region":"INTERNET"},
      "values":[[1553385600,"2569901"]]},{
      "metric":{
        "__name__":"egress_bandwidth",
        "pop":"lhr02",
        "traffic_region":"INTERNET"},
      "values":[[1553385600,"4442578"]]
    }
  ]}
}

Each polling time period contains two types of results, ingress and egress. Ingress measures the inbound traffic to the compute instance, while egress measures outbound traffic from your instance. For each traffic region, the values list contains an epoch timestamp and the total amount of data in bytes.

Examining the response above, the epoch time "1553385600" translates to Sunday, March 24, 2019 12:00:00 AM and the public ingress of  "2569901" bytes converts to 2.6MB.

---