> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# metrics

> cpln metrics — Run PromQL queries against your organization's metrics.

Query metrics

```none theme={null}
cpln metrics [SUBCOMMAND]
```

```text theme={null}
Commands:
  cpln metrics query [expr]  Execute a PromQL query

Options:
  --help  Show help  [boolean]
```

***

#### metrics query

Execute a PromQL query

**Usage**

```none theme={null}
cpln metrics query <promql> [OPTIONS]
```

<Tip>
  The PromQL expression can be passed as the positional argument or through the `--expr` option. Enclose it in single quotes so the shell does not expand it.
</Tip>

<Accordion title="Reference">
  ```text theme={null}
  Query options:
    --expr   PromQL expression (alternative to the positional argument)
    --from   Range start (ISO 8601, Unix timestamp, or relative duration, e.g., 2025-10-23T07:00:00Z, 7d, now-1h)
    --to     Range end (ISO 8601, Unix timestamp, or relative duration; defaults to now)
    --since  Lookback window before --to (or now); mutually exclusive with --from (default 1h when a range is requested)
    --step   Range query resolution step, e.g., 15s, 1m, 5m (default 60s)
    --time   Evaluation time for an instant query (ISO 8601, Unix timestamp, or relative like now-5m); mutually exclusive with --from/--to/--since

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * Instant query

  <CodeGroup>
    ```bash Command theme={null}
    cpln metrics query 'up' --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------+--------------------------------------------+--------------------------+-------+
    |METRIC |LABELS                                      |TIMESTAMP                 |VALUE  |
    |-------|--------------------------------------------|--------------------------|-------|
    |up     |{workload="api", location="aws-us-west-2"}  |2026-07-17T12:00:00.000Z  |1      |
    |up     |{workload="web", location="aws-us-west-2"}  |2026-07-17T12:00:00.000Z  |1      |
    +-------+--------------------------------------------+--------------------------+-------+
    ```
  </CodeGroup>

  * Range query over the last hour, sampled every five minutes

  <CodeGroup>
    ```bash Command theme={null}
    cpln metrics query 'sum(rate(http_requests_total[5m]))' --since 1h --step 5m --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------+--------+--------------------------+-------+
    |METRIC |LABELS  |TIMESTAMP                 |VALUE  |
    |-------|--------|--------------------------|-------|
    |       |        |2026-07-17T11:00:00.000Z  |42.7   |
    |       |        |2026-07-17T11:05:00.000Z  |45.1   |
    |       |        |2026-07-17T11:10:00.000Z  |39.8   |
    +-------+--------+--------------------------+-------+
    ```
  </CodeGroup>
</Accordion>

***