# Query Events (alias) in Inbox

| Method | Path | Summary |
| --- | --- | --- |
| `GET` | `/v0/inboxes/{inbox_id}/metrics` | [Query Events (alias) in Inbox](/content/docs/reference/api/metrics#query-events-alias-in-inbox/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/metrics/events` | [Query Events in Inbox](/content/docs/reference/api/metrics#query-events-in-inbox/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/metrics/rates` | [Query Rates in Inbox](/content/docs/reference/api/metrics#query-rates-in-inbox/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/metrics/usage` | [Query Usage in Inbox](/content/docs/reference/api/metrics#query-usage-in-inbox/index.html) |
| `GET` | `/v0/metrics` | [Query Events (alias)](/content/docs/reference/api/metrics#query-events-alias/index.html) |
| `GET` | `/v0/metrics/events` | [Query Events](/content/docs/reference/api/metrics#query-events/index.html) |
| `GET` | `/v0/metrics/rates` | [Query Rates](/content/docs/reference/api/metrics#query-rates/index.html) |
| `GET` | `/v0/metrics/usage` | [Query Usage](/content/docs/reference/api/metrics#query-usage/index.html) |
| `GET` | `/v0/pods/{pod_id}/metrics` | [Query Events (alias) in Pod](/content/docs/reference/api/metrics#query-events-alias-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/metrics/events` | [Query Events in Pod](/content/docs/reference/api/metrics#query-events-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/metrics/rates` | [Query Rates in Pod](/content/docs/reference/api/metrics#query-rates-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/metrics/usage` | [Query Usage in Pod](/content/docs/reference/api/metrics#query-usage-in-pod/index.html) |

## Query Events (alias) in Inbox

http

```
GET /v0/inboxes/{inbox_id}/metrics
```

**Warning**

Deprecated.

Same as Query Events (alias) (`GET /v0/metrics`), limited to the inbox.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `inbox_id` | `string` Required - ID of the inbox. |

#### Query parameters

| Field | Description |
| --- | --- |
| `event_types` | `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. |
| `start` | `string (date-time)` - Start of the range. Default: 24 hours before end. |
| `end` | `string (date-time)` - End of the range. Default: now; a later time is clamped to now. |
| `limit` | `integer` - Return at most this many points per series. |
| `descending` | `boolean` - Newest point first. |
| `period` | `integer` - Bucket size in seconds, 1 to 86400. Default 86400 (one bucket per UTC day). The range may hold at most 1000 buckets. |

#### Response

**200** Event counts by type (`application/json`)

Type: `Record<string, MetricBucket[]>`

#### Errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid request: error.type is validation and error.param names the field. |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `500` | Unexpected server error. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Events in Inbox

http

```
GET /v0/inboxes/{inbox_id}/metrics/events
```

Same as Query Events (`GET /v0/metrics/events`), limited to the inbox.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `inbox_id` | `string` Required - ID of the inbox. |

#### Query parameters

#### Response

**200** Event counts by type (`application/json`)

Type: `Record<string, MetricBucket[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics/events" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Rates in Inbox

http

```
GET /v0/inboxes/{inbox_id}/metrics/rates
```

Same as Query Rates (`GET /v0/metrics/rates`), limited to the inbox.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `inbox_id` | `string` Required - ID of the inbox. |

#### Query parameters

| Field | Description |
| --- | --- |
| `rate_types` | `string[]` - Rate types: bounce, complaint. Default: both. Another value is a 400. |
| `start` | `string (date-time)` - Start of the range. Default: 24 hours before end. |
| `end` | `string (date-time)` - End of the range. Default: now; a later time is clamped to now. |
| `limit` | `integer` - Return at most this many points per series. |
| `descending` | `boolean` - Newest point first. |
| `period` | `integer` - How often a point is sampled, in seconds, 60 to 86400. Default 3600. The range may hold at most 1000 points. |
| `window` | `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. |

#### Response

**200** Rates by type (`application/json`)

Type: `Record<string, RatePoint[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics/rates" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Usage in Inbox

http

```
GET /v0/inboxes/{inbox_id}/metrics/usage
```

Same as Query Usage (`GET /v0/metrics/usage`), limited to the inbox.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `inbox_id` | `string` Required - ID of the inbox. |

#### Query parameters

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

#### Response

**200** Usage by type (`application/json`)

Type: `Record<string, UsagePoint[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics/usage" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Events (alias)

http

```
GET /v0/metrics
```

**Warning**

Deprecated.

Alias of `GET /v0/metrics/events`.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Query parameters

#### Response

**200** Event counts by type (`application/json`)

Type: `Record<string, MetricBucket[]>`

#### Errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid request: error.type is validation and error.param names the field. |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register). |
| `500` | Unexpected server error. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/metrics" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Events

http

```
GET /v0/metrics/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.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Query parameters

#### Response

**200** Event counts by type (`application/json`)

Type: `Record<string, MetricBucket[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/metrics/events" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Rates

http

```
GET /v0/metrics/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.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Query parameters

#### Response

**200** Rates by type (`application/json`)

Type: `Record<string, RatePoint[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/metrics/rates" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Usage

http

```
GET /v0/metrics/usage
```

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

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Query parameters

#### Response

**200** Usage by type (`application/json`)

Type: `Record<string, UsagePoint[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/metrics/usage" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Events (alias) in Pod

http

```
GET /v0/pods/{pod_id}/metrics
```

**Warning**

Deprecated.

Same as Query Events (alias) (`GET /v0/metrics`), limited to the pod.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `pod_id` | `string` Required - ID of the pod. |

#### Query parameters

#### Response

**200** Event counts by type (`application/json`)

Type: `Record<string, MetricBucket[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Events in Pod

http

```
GET /v0/pods/{pod_id}/metrics/events
```

Same as Query Events (`GET /v0/metrics/events`), limited to the pod.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `pod_id` | `string` Required - ID of the pod. |

#### Query parameters

#### Response

**200** Event counts by type (`application/json`)

Type: `Record<string, MetricBucket[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics/events" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Rates in Pod

http

```
GET /v0/pods/{pod_id}/metrics/rates
```

Same as Query Rates (`GET /v0/metrics/rates`), limited to the pod.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `pod_id` | `string` Required - ID of the pod. |

#### Query parameters

#### Response

**200** Rates by type (`application/json`)

Type: `Record<string, RatePoint[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics/rates" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```

## Query Usage in Pod

http

```
GET /v0/pods/{pod_id}/metrics/usage
```

Same as Query Usage (`GET /v0/metrics/usage`), limited to the pod.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `pod_id` | `string` Required - ID of the pod. |

#### Query parameters

#### Response

**200** Usage by type (`application/json`)

Type: `Record<string, UsagePoint[]>`

#### Errors

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### Example

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics/usage" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "key": "value"
}
```