# Query metrics

Query the CPU, network, or volume metrics of one resource over a time window with the GraphQL API, and choose the period and statistic.

Use the `observability.metrics` query to get a series of data points for one compute instance, volume, or network interface. You choose the metrics, the time window, the length of each period, and whether each data point is a per-second rate or a total increase.

## Before you begin [#before-you-begin]

<BeforeYouBegin>

- The URN of the project that holds the resource you want metrics for. The steps use it to find the resource’s URN.
- Permission `observability.metric.get` on the resource. The built-in Owner and Viewer roles include it. See [Built-in roles](/docs/iam/roles).
- An access token for the API. The examples get one from the `origin` CLI with `origin id token`. See [Use the GraphQL API](/docs/platform/access/api).

</BeforeYouBegin>

## Query the metrics [#query-the-metrics]

1. Find the URN of the resource. Each command lists the resources of a project with their `urn` field:

   ```sh
   origin compute list-instances --project-urn <project-urn>
   origin storage list-volumes --project-urn <project-urn>
   origin network list-network-interfaces --project-urn <project-urn>
   ```

1. Pick the metric names for that resource type. An instance has `oc_compute_instance_cpu_seconds_total`; a volume and a network interface each have two metrics. See [Metrics reference](/docs/observability/reference/metrics).
1. Use a `periodSeconds` of at least 60. The platform collects a value every 30 seconds, and each data point needs two collected values inside its period; a shorter period often returns no data points.
1. Keep the total number of data points, across all metrics in the query, at or below 11,000. For example, one metric over 7 days at a 300-second period is 2,017 data points.
1. Make `from` a multiple of the period (for example, a full hour) so data points line up with clock times.
1. Save the request as `metrics-query.json`. This example asks for the CPU use of an instance as a per-second rate, in 5-minute periods, over 15 minutes:

   ```json
   {
     "query": "query Metrics($input: MetricQueryInput!) { observability { metrics(input: $input) { metricName resourceUrn unit dataPoints { timestamp value } } } }",
     "variables": {
       "input": {
         "resourceUrn": "<instance-urn>",
         "metricNames": ["oc_compute_instance_cpu_seconds_total"],
         "from": "2026-10-03T10:00:00Z",
         "to": "2026-10-03T10:15:00Z",
         "periodSeconds": 300,
         "statistic": "RATE"
       }
     }
   }
   ```

   Formatted, the GraphQL query in the `query` field reads:

   ```graphql
   query Metrics($input: MetricQueryInput!) {
     observability {
       metrics(input: $input) {
         metricName
         resourceUrn
         unit
         dataPoints {
           timestamp
           value
         }
       }
     }
   }
   ```

1. Send the request:

   ```sh
   curl -s https://api.origincloud.eu/graphql \
     -H "$(origin id token --as-header --raw)" \
     -H "Content-Type: application/json" \
     --data @metrics-query.json
   ```

1. Check the response. It contains one series per metric name you asked for, in the same order. For `RATE` on `oc_compute_instance_cpu_seconds_total`, a value of `0.5` means the instance used half a vCPU on average during that period. Example output (illustrative):

   ```json
   {
     "data": {
       "observability": {
         "metrics": [
           {
             "metricName": "oc_compute_instance_cpu_seconds_total",
             "resourceUrn": "<instance-urn>",
             "unit": "seconds",
             "dataPoints": [
               { "timestamp": "2026-10-03T10:00:00+00:00", "value": 0.12 },
               { "timestamp": "2026-10-03T10:05:00+00:00", "value": 0.48 },
               { "timestamp": "2026-10-03T10:10:00+00:00", "value": 1.73 },
               { "timestamp": "2026-10-03T10:15:00+00:00", "value": 0.51 }
             ]
           }
         ]
       }
     }
   }
   ```

   Each data point covers the period that ends at its timestamp. The unit is the unit of the counter, so a `RATE` of a seconds counter is seconds per second.

   Both ends of the window are included: data points fall on `from`, every `periodSeconds` after it, and `to`, which is why a 15-minute window at 300 seconds returns four points. The first point, at `from`, covers the period before `from` (here 09:55 to 10:00). To cover only the window itself, set `from` one period later.

A series with an empty `dataPoints` list means the platform has no values for that resource and metric in the window. Common reasons are an instance that was stopped, a volume or network interface that wasn’t attached to a running instance, a metric name that belongs to another resource type, or a window older than the 90 days the platform keeps metrics.

<Callout type="note">

Each successful query is billed as one request, however many metrics or data points it returns. A rejected query isn’t billed. See [`observability_api_request`](/docs/pricing/reference/price-list-api#observability_api_request).

</Callout>

If the query returns an error, look up its `extensions.code` in [Errors](/docs/observability/reference/metrics#errors).

## Related [#related]

- [Metrics reference](/docs/observability/reference/metrics) – every metric, argument, limit, and error.
- [What is Origin Cloud Observability?](/docs/observability) – how counters, `RATE`, and `INCREASE` work.
- [Use the GraphQL API](/docs/platform/access/api) – authenticating against the GraphQL API.