To query ACLP metrics for Linodes, run a POST request containing a JSON payload with your desired metrics and an aggregate_function (like min, max, or avg). You can request multiple metrics in one payload or make separate requests for each.

Before you begin

Set up your authentication and learn what metrics are available to query for Linodes.

Get an access token

To use Monitor API operations, you need to generate a JWE-format token for inclusion in the call.

Follow the detailed guide to Authenticate Monitor API operations.

List Linodes' metrics

1. Run the List metrics for a service type operation, targeting linode as serviceType to see the list of supported metrics for Linodes.
2. Review the data objects in the response. Store the metric identifiers from the metric fields. This is how the metric is called out in other Monitor operations in the API, and you can use these identifiers to query individual metrics using the Get an entity's metrics operation:
   • Query Linode's CPU usage
   • Query Linode's inbound network traffic
   • Query Linode's outbound network traffic
   • Query Linode's disk operations

📘

The Get an entity's metrics operation uses a different URL and version from standard Linode API operations. Verify you're using the URL with the monitor-api.linode.com hostname and include v2 (or v2beta) as the version in the URL.

Query Linode's CPU usage

This workflow covers how to retrieve CPU usage metrics using the ACLP formatting.

1. Run the Get an entity's metric operation, targeting linode as serviceType and passing the stored token as a Bearer authorization header. Below is an example using cURL:

   cURL

   curl --request POST \
        --url https://monitor-api.linode.com/v2/monitor/services/linode/metrics \
        --header 'accept: application/json' \
        --header "authorization: Bearer abc123" \
        --header 'content-type: application/json' \
        --data '

2. In the request, apply your Linode's id value in entity_ids and define the vm_cpu_usage_pct metric and your desired aggregation. Configure the remaining fields as necessary and submit the request. For example:

   JSON

   {
     "entity_ids": [100213616],
     "group_by": ["entity_id"],
     "relative_time_duration": {
       "unit": "min",
       "value": 30
     },
     "metrics": [
       {
         "aggregate_function": "avg",
         "name": "vm_cpu_usage_pct"
       }
     ]
   }

3. Review the CPU usage metrics information in the response. Note that in values, the timestamp is now in seconds and the CPU usage value is capped at 100%.

   JSON

   {
     "status": "success",
     "isPartial": false,
     "data": {
       "resultType": "matrix",
       "result": [
         {
           "metric": {
             "entity_id": "100213616",
             "metric_name": "avg_vm_cpu_usage_pct"
           },
           "values": [
             [
               1786624782,
               "64" 
             ]        
           ]
         }
       ]
     },
     "stats": {
       "executionTimeMsec": 7,
       "seriesFetched": "8"
     }
   }

Query Linode's inbound network traffic

This workflow covers how to retrieve inbound network traffic metrics using the ACLP formatting.

1. Run the Get an entity's metric operation, targeting linode as serviceType and passing the stored token as a Bearer authorization header. Below is an example using cURL:

   cURL

   curl --request POST \
        --url https://monitor-api.linode.com/v2/monitor/services/linode/metrics \
        --header 'accept: application/json' \
        --header "authorization: Bearer abc123" \
        --header 'content-type: application/json' \
        --data '

2. In the request:

   1. Apply your Linode's id value in entity_ids.

   2. Define the vm_network_traffic_rate_kbps metric and your desired aggregation.

   3. Apply filters for the publicin and privatein patterns.

   4. Configure the remaining fields as necessary and submit the request.
      For example:

      JSON

      {
        "entity_ids": [100213616],
        "group_by": ["entity_id"],
        "relative_time_duration": {
          "unit": "min",
          "value": 30
        },
        "filters": [
          {
            "dimension_label": "pattern",
            "operator": "in",
            "value": "publicin,privatein"
          }
        ],
        "metrics": [
          {
            "aggregate_function": "avg",
            "name": "vm_network_traffic_rate_kbps"
          }
        ]
      }

3. Review the inbound network traffic metrics information in the response. Note that in values, the network unit is now in kilobits per second (kbps).

   JSON

   {
     "status": "success",
     "isPartial": false,
     "data": {
       "resultType": "matrix",
       "result": [
         {
           "metric": {
             "entity_id": "100213616",
             "metric_name": "avg_vm_network_traffic_rate_kbps"
           },
           "values": [
             [
               1786624782,
               "4.926"
             ]        
           ]
         }
       ]
     },
     "stats": {
       "executionTimeMsec": 5,
       "seriesFetched": "4"
     }
   }

Query Linode's outbound network traffic

This workflow covers how to retrieve outbound network traffic metrics using the ACLP formatting.

1. Run the Get an entity's metric operation, targeting linode as serviceType and passing the stored token as a Bearer authorization header. Below is an example using cURL:

   cURL

   curl --request POST \
        --url https://monitor-api.linode.com/v2/monitor/services/linode/metrics \
        --header 'accept: application/json' \
        --header "authorization: Bearer abc123" \
        --header 'content-type: application/json' \
        --data '

2. In the request:

   1. Apply your Linode's id value in entity_ids.

   2. Define the vm_network_traffic_rate_kbps metric and your desired aggregation.

   3. Apply filters for the publicout and privateout patterns.

   4. Configure the remaining fields as necessary and submit the request.
      For example:

      JSON

      {
        "entity_ids": [100213616],
        "group_by": ["entity_id"],
        "relative_time_duration": {
          "unit": "min",
          "value": 30
        },
        "filters": [
          {
            "dimension_label": "pattern",
            "operator": "in",
            "value": "publicout,privateout"
          }
        ],
        "metrics": [
          {
            "aggregate_function": "avg",
            "name": "vm_network_traffic_rate_kbps"
          }
        ]
      }

3. Review the outbound network traffic metrics information in the response. Note that in values, the network unit is now in kilobits per second (kbps).

   JSON

   {
     "status": "success",
     "isPartial": false,
     "data": {
       "resultType": "matrix",
       "result": [
         {
           "metric": {
             "entity_id": "100213616",
             "metric_name": "avg_vm_network_traffic_rate_kbps"
           },
           "values": [
             [
               1786624782,
               "0.16037333333333334"
             ]        
           ]
         }
       ]
     },
     "stats": {
       "executionTimeMsec": 2,
       "seriesFetched": "4"
     }
   }

Query Linode's disk operations

This workflow covers how to retrieve Linode's disk operations metrics using the ACLP formatting.

1. Run the Get an entity's metric operation, targeting linode as serviceType and passing the stored token as a Bearer authorization header. Below is an example using cURL:

   cURL

   curl --request POST \
        --url https://monitor-api.linode.com/v2/monitor/services/linode/metrics \
        --header 'accept: application/json' \
        --header "authorization: Bearer abc123" \
        --header 'content-type: application/json' \
        --data '

2. In the request, apply your Linode's id value in entity_ids and define the vm_disk_io_rate_iops metric and your desired aggregation. Configure the remaining fields as necessary and submit the the request. For example:

   JSON

   {
     "entity_ids": [100213616],
     "group_by": ["entity_id"],
     "relative_time_duration": {
       "unit": "min",
       "value": 30
     },
     "metrics": [
       {
         "aggregate_function": "avg",
         "name": "vm_disk_io_rate_iops"
       }
     ]
   }

3. Review the disk operations metrics information in the response.

   JSON

   {
     "status": "success",
     "isPartial": false,
     "data": {
       "resultType": "matrix",
       "result": [
         {
           "metric": {
             "entity_id": "100213616",
             "metric_name": "avg_vm_disk_io_rate_iops"
           },
           "values": [
             [
               1786624782,
               "0.6766666666666666"
             ]
            ]
         }
       ]
     },
     "stats": {
       "executionTimeMsec": 3,
       "seriesFetched": "4"
     }
   }