<!-- Generated by `just docs` from proto/automaton/v1/usage.proto. Edit the source, not this file. -->

# UsageService

What this project has used, aggregated from the same receipts everything else reads. Scoped to the key's own project; a request cannot ask about another one.

Every call is a POST to `https://api.atmon.ai/automaton.v1.UsageService/<Call>` with a JSON body, and authenticates with `Authorization: Bearer <your project key>`. Field names in JSON are lowerCamelCase, so the field written `tool_slug` below is `toolSlug` on the wire. [How to call the API](./index.md) has the whole convention.

## Calls

| Call | Request | Response | Summary |
| --- | --- | --- | --- |
| `GetUsage` | `GetUsageRequest` | `GetUsageResponse` | Aggregates the project's ledger rows over a window, grouped by day, toolkit, or tool. |

### GetUsage

Aggregates the project's ledger rows over a window, grouped by day,
toolkit, or tool. Every recorded call counts, whatever its status, so the
succeeded, failed, and denied columns partition the total.

Request `GetUsageRequest`, response `GetUsageResponse`.

```http
POST /automaton.v1.UsageService/GetUsage HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "from": "2026-01-31T09:15:00Z",
  "to": "2026-01-31T09:15:00Z",
  "groupBy": "..."
}
```

The response:

```json
{
  "rows": [{
    "key": "...",
    "calls": 0,
    "succeeded": 0,
    "failed": 0,
    "denied": 0
  }],
  "totalCalls": 0
}
```

## Messages

### GetUsageRequest

| Field | Type | # | Notes |
| --- | --- | --- | --- |
| `from` | `google.protobuf.Timestamp` | 1 | inclusive; zero means 30 days before to |
| `to` | `google.protobuf.Timestamp` | 2 | exclusive; zero means now |
| `group_by` | `string` | 3 | "day" \| "toolkit" \| "tool" (default "day") |

### GetUsageResponse

| Field | Type | # | Notes |
| --- | --- | --- | --- |
| `rows` | repeated `UsageRow` | 1 | ordered by key; for "day" that is chronological |
| `total_calls` | `int64` | 2 |  |

### UsageRow

| Field | Type | # | Notes |
| --- | --- | --- | --- |
| `key` | `string` | 1 | the group value: "2026-07-30", "github", "github.create_issue" |
| `calls` | `int64` | 2 | all recorded calls, whatever their status |
| `succeeded` | `int64` | 3 |  |
| `failed` | `int64` | 4 |  |
| `denied` | `int64` | 5 | refused by the mutation gate or by policy |