# Observability

> The Observability operations of the Kabu API: your own usage, request logs and delivery timelines.

Your own usage, request logs and delivery timelines.

Generated from the contract, version `2.0.0-draft.2` ([OpenAPI](/openapi.yaml)). Base URL `https://usekabu.com/api`. Errors are problem details, each [code](/docs/errors) with its own page.

## `GET /v2/messages/{message_id}/deliveries` · Delivery timeline for a message

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `observability:read`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `message_id` | path | string | yes | A `msg_…` id. |
| `limit` | query | integer, from 1 to 100 | no |  |
| `after` | query | string | no | Opaque cursor from next_cursor. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `200` | OK | [DeliveryAttemptList](#schema-DeliveryAttemptList) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl "https://usekabu.com/api/v2/messages/$MESSAGE_ID/deliveries" \
  -H "Authorization: Bearer $KABU_API_KEY"
```

## `GET /v2/usage` · Usage against plan limits, per agent

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `usage:read`.
- **Signed-in humans:** `member`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `project` | query | string | no |  |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `200` | OK | [Usage](#schema-Usage) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl "https://usekabu.com/api/v2/usage" \
  -H "Authorization: Bearer $KABU_API_KEY"
```

## `GET /v2/request_logs` · Your recent API requests (24 h, metadata only)

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `observability:read`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer, from 1 to 100 | no |  |
| `after` | query | string | no | Opaque cursor from next_cursor. |
| `status` | query | integer | no |  |
| `route` | query | string | no |  |
| `request_id` | query | string | no |  |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `200` | OK | [RequestLogList](#schema-RequestLogList) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl "https://usekabu.com/api/v2/request_logs" \
  -H "Authorization: Bearer $KABU_API_KEY"
```

## Schemas

### DeliveryAttemptList

| Property | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` | yes |  |
| `data` | array of [DeliveryAttempt](#schema-DeliveryAttempt) | yes |  |
| `has_more` | boolean | yes |  |
| `next_cursor` | string or null | yes |  |

### DeliveryAttempt

| Property | Type | Required | Description |
|---|---|---|---|
| `channel` | [Channel](/docs/api/messages#schema-Channel) | yes | Open enum. Known values are `ChannelKnown`; accept and ignore unknown values. |
| `recipient` | string | yes |  |
| `status` | string | yes |  |
| `detail` | string or null | yes |  |
| `at` | [Timestamp](/docs/api/messages#schema-Timestamp) | yes |  |

### Usage

| Property | Type | Required | Description |
|---|---|---|---|
| `object` | `"usage"` | yes |  |
| `plan` | string | yes |  |
| `period_start` | [Timestamp](/docs/api/messages#schema-Timestamp) | yes |  |
| `period_end` | [Timestamp](/docs/api/messages#schema-Timestamp) | yes |  |
| `messages` | [UsageCounter](#schema-UsageCounter) | yes |  |
| `open_asks` | [UsageCounter](#schema-UsageCounter) | yes |  |
| `waits` | [UsageCounter](#schema-UsageCounter) | yes |  |
| `media_bytes` | [UsageCounter](#schema-UsageCounter) | yes |  |
| `tts_characters` | [UsageCounter](#schema-UsageCounter) | yes |  |
| `by_agent` | array of object, at most 50 items | yes | Top 50 agents by messages; the full breakdown belongs to reports. |
| `by_agent[].agent` | string | yes |  |
| `by_agent[].messages` | integer | yes |  |
| `by_agent[].asks` | integer | yes |  |

### UsageCounter

| Property | Type | Required | Description |
|---|---|---|---|
| `used` | integer | yes |  |
| `limit` | integer or null | yes |  |

### RequestLogList

| Property | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` | yes |  |
| `data` | array of [RequestLog](#schema-RequestLog) | yes |  |
| `has_more` | boolean | yes |  |
| `next_cursor` | string or null | yes |  |

### RequestLog

Metadata only: never bodies, secrets or links. Kept 24 h.

| Property | Type | Required | Description |
|---|---|---|---|
| `request_id` | string | yes |  |
| `method` | string | yes |  |
| `route` | string | yes |  |
| `status` | integer | yes |  |
| `duration_ms` | integer | yes |  |
| `key` | string or null | yes |  |
| `trace_id` | string or null | yes |  |
| `code` | string or null | yes |  |
| `at` | [Timestamp](/docs/api/messages#schema-Timestamp) | yes |  |