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

# Metrics

> List metric streams and query data points from the AgentVista metrics API.

AgentVista stores metrics ingested via the OTLP endpoint as named metric streams with typed data points. You can query those streams and filter by labels and time range through the dashboard API.

<Note>
  To ingest metrics data, use the [OTLP ingestion endpoint](/api/otlp). The endpoints on this page are read-only dashboard endpoints.
</Note>

***

## List metric streams

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/dashboard/metrics/ \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`GET /dashboard/metrics/`

Returns all named metric streams owned by the authenticated user, including the total number of data points stored for each metric. Results are ordered alphabetically by name.

### Response — 200

An array of metric stream objects.

<ResponseField name="name" type="string">
  Metric name (e.g. `"system.cpu.utilization"`).
</ResponseField>

<ResponseField name="metric_type" type="string">
  OTLP metric type (e.g. `"gauge"`, `"sum"`, `"histogram"`).
</ResponseField>

<ResponseField name="unit" type="string">
  Unit of measurement (e.g. `"1"`, `"ms"`, `"By"`).
</ResponseField>

<ResponseField name="description" type="string">
  Human-readable description from the OTLP payload.
</ResponseField>

<ResponseField name="data_point_count" type="number">
  Total number of data points stored for this metric stream.
</ResponseField>

```json Example response theme={null}
[
  {
    "name": "system.cpu.utilization",
    "metric_type": "gauge",
    "unit": "1",
    "description": "CPU utilization as a fraction of capacity",
    "data_point_count": 14400
  },
  {
    "name": "http.server.request.duration",
    "metric_type": "histogram",
    "unit": "ms",
    "description": "HTTP server request duration",
    "data_point_count": 8291
  }
]
```

***

## Query metric data points

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.agentvista.dev/api/v1/dashboard/metrics/query?name=system.cpu.utilization&start=2024-01-15T00:00:00Z&end=2024-01-15T23:59:59Z&limit=500" \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```bash With label filter theme={null}
  curl "https://api.agentvista.dev/api/v1/dashboard/metrics/query?name=system.cpu.utilization&labels=%7B%22host%22%3A%22web-1%22%7D" \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`GET /dashboard/metrics/query`

Queries data points for a named metric stream with optional label and time range filters. Returns `404` if no metric with the given name exists for the authenticated user.

### Query parameters

<ParamField query="name" type="string" required>
  Metric name to query (e.g. `"system.cpu.utilization"`).
</ParamField>

<ParamField query="labels" type="string">
  JSON-encoded label filter object (URL-encoded). Only data points whose labels contain all specified key-value pairs are returned. Example: `{"host":"web-1"}`. Uses subset matching — a data point with labels `{"host":"web-1","region":"us-east"}` matches a filter of `{"host":"web-1"}`.
</ParamField>

<ParamField query="start" type="string">
  ISO 8601 datetime. Only data points at or after this time are returned.
</ParamField>

<ParamField query="end" type="string">
  ISO 8601 datetime. Only data points at or before this time are returned.
</ParamField>

<ParamField query="limit" type="number" default="1000">
  Maximum number of data points to return. Data points are ordered newest-first.
</ParamField>

### Response — 200

<ResponseField name="name" type="string">
  Metric name.
</ResponseField>

<ResponseField name="metric_type" type="string">
  Metric type (e.g. `"gauge"`, `"sum"`, `"histogram"`).
</ResponseField>

<ResponseField name="unit" type="string">
  Unit of measurement.
</ResponseField>

<ResponseField name="data_points" type="object[]">
  Matching data points ordered newest-first.

  <Expandable title="data point fields">
    <ResponseField name="value" type="number">
      Numeric value of the data point.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp when the data point was recorded.
    </ResponseField>

    <ResponseField name="labels" type="object">
      Key-value label pairs attached to this data point (e.g. `{"host": "web-1", "region": "us-east"}`).
    </ResponseField>
  </Expandable>
</ResponseField>

```json Example response theme={null}
{
  "name": "system.cpu.utilization",
  "metric_type": "gauge",
  "unit": "1",
  "data_points": [
    {
      "value": 0.72,
      "timestamp": "2024-01-15T12:05:00Z",
      "labels": { "host": "web-1", "region": "us-east" }
    },
    {
      "value": 0.65,
      "timestamp": "2024-01-15T12:04:00Z",
      "labels": { "host": "web-1", "region": "us-east" }
    }
  ]
}
```