---
title: "metrics"
description: "Counts and rates. The `machinemail metrics` commands: arguments, flags, examples and the API routes they call."
canonical: "https://machinemail.dev/docs/cli/commands/metrics"
---

# metrics

> Counts and rates. The `machinemail metrics` commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/metrics

Counts and rates.

| Command                             | Summary      |
| ----------------------------------- | ------------ |
| [`metrics events`](#metrics-events) | Query events |
| [`metrics rates`](#metrics-rates)   | Query rates  |
| [`metrics usage`](#metrics-usage)   | Query usage  |

Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags).

## metrics events

Query events.

Counts of events per event type over time, in buckets of --period seconds (default one day), over the last 24 hours unless --start and --end say otherwise. message.received includes its sub-types (spam, blocked, unauthenticated, quarantined). At most 100,000 events are counted per query.

Requires the metrics\_read permission.

```bash
machinemail metrics events [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Only this inbox. |
| `--pod <pod-id>` | `string` |  | Only this pod. |
| `-e, --event-types <value>` | `string[]` |  | Event types to count: message.received, message.received.spam, message.received.blocked, message.received.unauthenticated, message.received.quarantined, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified (the default is all of them). message.received counts every inbound message, including the message.received.* sub-types, which are also reported under their own keys. Other values give a series of zeros. Repeat the flag for several values. |
| `--start <time>` | `string` |  | Start of the range. Default: 24 hours before --end. Default: `24 hours before --end`. |
| `--end <time>` | `string` |  | End of the range. Default: now; a later time is clamped to now. Default: `now`. |
| `--limit <n>` | `integer` |  | Return at most this many points per series. |
| `--descending` | `boolean` |  | Newest point first. |
| `--period <n>` | `integer` |  | Bucket size in seconds, 1 to 86400. Default 86400 (one bucket per UTC day). The range may hold at most 1000 buckets. Default: `86400`. |

#### Examples

```bash
machinemail metrics events
machinemail metrics events --inbox agent@machinemail.dev
```

#### API

- [`GET /v0/metrics/events`](https://machinemail.dev/docs/reference/api/metrics#query-events)
- [`GET /v0/inboxes/{inbox_id}/metrics/events`](https://machinemail.dev/docs/reference/api/metrics#query-events-in-inbox) with `--inbox`
- [`GET /v0/pods/{pod_id}/metrics/events`](https://machinemail.dev/docs/reference/api/metrics#query-events-in-pod) with `--pod`

## metrics rates

Query rates.

Rolling bounce and complaint rates. At each --period grid point: the bounced (or complained) messages over the preceding --window, divided by the messages sent over the same window, with the send count alongside. Defaults: the last 24 hours, --period 3600, --window 86400.

Requires the metrics\_read permission.

```bash
machinemail metrics rates [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Only this inbox. |
| `--pod <pod-id>` | `string` |  | Only this pod. |
| `--rate-types <value>` | `string[]` |  | Rate types: bounce, complaint. Default: both. Another value is a 400. Repeat the flag for several values. Default: `both`. |
| `--start <time>` | `string` |  | Start of the range. Default: 24 hours before --end. Default: `24 hours before --end`. |
| `--end <time>` | `string` |  | End of the range. Default: now; a later time is clamped to now. Default: `now`. |
| `--limit <n>` | `integer` |  | Return at most this many points per series. |
| `--descending` | `boolean` |  | Newest point first. |
| `--period <n>` | `integer` |  | How often a point is sampled, in seconds, 60 to 86400. Default 3600. The range may hold at most 1000 points. Default: `3600`. |
| `--window <n>` | `integer` |  | How far back each point looks, in seconds: a whole multiple of --period, at most 2592000 (30 days). Default 86400 when that is a multiple of --period, otherwise --period. Default: `86400 when that is a multiple of --period`. |

#### Examples

```bash
machinemail metrics rates
machinemail metrics rates --inbox agent@machinemail.dev
```

#### API

- [`GET /v0/metrics/rates`](https://machinemail.dev/docs/reference/api/metrics#query-rates)
- [`GET /v0/inboxes/{inbox_id}/metrics/rates`](https://machinemail.dev/docs/reference/api/metrics#query-rates-in-inbox) with `--inbox`
- [`GET /v0/pods/{pod_id}/metrics/rates`](https://machinemail.dev/docs/reference/api/metrics#query-rates-in-pod) with `--pod`

## metrics usage

Query usage.

Current usage in the scope. Usage history is not kept yet: each series has a single point, at --end, with the value now.

Requires the metrics\_read permission.

```bash
machinemail metrics usage [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Only this inbox. |
| `--pod <pod-id>` | `string` |  | Only this pod. |
| `--usage-types <value>` | `string[]` |  | Usage types: storage_bytes, message_count, thread_count, inbox_count, pod_count, domain_count. Default: all. Another value is a 400. Repeat the flag for several values. Default: `all`. |
| `--start <time>` | `string` |  | Start of the range. Default: 24 hours before --end. Default: `24 hours before --end`. |
| `--end <time>` | `string` |  | End of the range. Default: now; a later time is clamped to now. Default: `now`. |
| `--limit <n>` | `integer` |  | Return at most this many points per series. |
| `--descending` | `boolean` |  | Newest point first. |
| `--period <n>` | `integer` |  | Accepted for AgentMail compatibility; usage has no history, so there is one point whatever the period. |

#### Examples

```bash
machinemail metrics usage
machinemail metrics usage --inbox agent@machinemail.dev
```

#### API

- [`GET /v0/metrics/usage`](https://machinemail.dev/docs/reference/api/metrics#query-usage)
- [`GET /v0/inboxes/{inbox_id}/metrics/usage`](https://machinemail.dev/docs/reference/api/metrics#query-usage-in-inbox) with `--inbox`
- [`GET /v0/pods/{pod_id}/metrics/usage`](https://machinemail.dev/docs/reference/api/metrics#query-usage-in-pod) with `--pod`