> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aegis-kyt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GET /v2/me/usage
> Current quota + paginated call history for the authenticated key.
**Auth:** Required · **Cost:** Free (no quota debit) · **Use case:** Quota
visibility for self-service dashboards + pre-flight checks
Returns the same data shown in your kabinet at
[app.aegis-kyt.com/account?tab=api](https://app.aegis-kyt.com/account?tab=api).
Single source of truth — rows from `user_api_usage`, billing snapshot
from `user_billing`.
Use this endpoint to:
* Surface "X of Y calls remaining" inside your own admin UI.
* Detect quota exhaustion **before** firing a paid call (avoids a
402 round-trip).
* Audit which addresses your key has screened (CSV / SOC2 reporting).
## Request
```bash theme={null}
curl -H "Authorization: Bearer aeg_YOUR_KEY_HERE" \
"https://api.aegis-kyt.com/v2/me/usage?page=1&limit=20"
```
| Query param | Type | Default | Notes |
| ----------- | --------- | ------- | ----------------------------------------- |
| `page` | int ≥ 1 | `1` | 1-indexed page number |
| `limit` | int 1–100 | `20` | Rows per page |
| `since` | ISO date | — | Filter to rows with `created_at >= since` |
## Response 200
```json theme={null}
{
"schema_version": 1,
"billing": {
"monthly_quota": 15,
"used_this_month": 3,
"remaining": 12,
"period_start": "2026-05-01",
"period_end": null
},
"key": {
"prefix": "aeg_x4k2",
"name": "production"
},
"rows": [
{
"id": 842,
"endpoint": "/v2/screen",
"address": "TScSLnUodZVsgoGchZspDoimDjDB9bwqVv",
"network": "TRON",
"provider": "Aegis",
"risk_level": "medium",
"risk_score": 50,
"quota_cost": 1,
"http_status": 200,
"elapsed_ms": 90,
"created_at": "2026-05-11T14:33:12.481Z"
}
],
"total": 3,
"page": 1,
"total_pages": 1
}
```
### `billing` object
| Field | Type | Notes |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------- |
| `monthly_quota` | int \| null | Plan-level cap. `null` when the user has no billing row yet (pre-onboarding state) |
| `used_this_month` | int \| null | Quota units already consumed in the current period |
| `remaining` | int \| null | `max(0, monthly_quota - used_this_month)` |
| `period_start` | ISO date \| null | Start of the current billing period (UTC) |
| `period_end` | ISO date \| null | Reserved for future plans with non-monthly cadences |
When `monthly_quota` is `null`, the user has not been onboarded onto a
paid plan yet. Calls will return 402 until the kabinet provisions a
plan.
### `rows[]` — usage history
Each row mirrors one entry in `user_api_usage`.
| Field | Type | Notes |
| ------------- | ----------------- | -------------------------------------------------------------------------- |
| `id` | int | Monotonic per-user ID |
| `endpoint` | string | Path called (`/v2/check-address`, etc.) |
| `address` | string \| null | Looked-up address. Null for non-screening endpoints |
| `network` | string \| null | `BSC` / `ETH` / `TRON` / … |
| `provider` | string \| null | `Aegis` / `provider_b` / `provider_a` / `consensus`. Null for free probes |
| `risk_level` | enum \| null | `none` / `low` / `medium` / `high` / `critical` / `sanctioned` |
| `risk_score` | int 0–100 \| null | Aggregated score from the provider |
| `quota_cost` | int | Units debited for this call. `0` for free + refunded calls |
| `http_status` | int | Wire status code (`200`, `402`, `502`, …) |
| `elapsed_ms` | int \| null | Server-side latency |
| `created_at` | RFC 3339 | UTC timestamp |
### Pagination
| Field | Type | Notes |
| ------------- | ---- | ---------------------------------------- |
| `total` | int | Total matching rows (respecting `since`) |
| `page` | int | Echo of the requested page |
| `total_pages` | int | `ceil(total / limit)` — always ≥ 1 |
## Errors
| HTTP | code | Why |
| ---- | ----------------- | --------------------------------------------------- |
| 401 | `missing_api_key` | No `Authorization: Bearer …` header |
| 401 | `invalid_api_key` | Unknown / revoked key |
| 422 | validation | `page < 1` / `limit` out of 1–100 / non-ISO `since` |
## Notes
* This endpoint **does not** debit quota — call it as often as you
like.
* Best-effort write semantics on `user_api_usage`: in extremely rare
cases (Supabase write fails) a paid call's row may be missing.
Billing is unaffected — it's computed from `consume_quota` on the
hot path, not from this audit table.
* For programmatic billing-period detection, also check `period_start`
changes — when it increments, your monthly quota has reset.
## See also
* [V2 API key (auth)](/authentication/v2-api-key) — how to issue + rotate
* [V2 introduction](/api-reference/v2-introduction) — quota + refund
semantics
* [POST /v2/screen](/api-reference/v2-screen)
— the typical paid call you'll see in `rows[]`
## OpenAPI
````yaml GET /me/usage
openapi: 3.1.0
info:
description: >-
Public, subscription-billed AML API. Send `Authorization: Bearer aeg_`
on every call. See the user kabinet at
https://app.aegis-kyt.com/account?tab=api to generate a key.
title: Aegis Public API
version: 2.0.0
servers:
- description: Production
url: https://api.aegis-kyt.com/v2
security: []
paths:
/me/usage:
get:
tags:
- v2-public
summary: API key usage history + current quota
description: >-
Returns the same data the user-facing kabinet shows under /account → API
tab. Single source of truth: rows from `user_api_usage`; the `billing`
block shape depends on the account's active billing mode — `model:
"quota"` (monthly unit allowance from `user_billing`) or `model:
"ledger"` (USD balance from the same source as `GET /v2/balance`).
operationId: me_usage_me_usage_get
parameters:
- in: query
name: page
required: false
schema:
default: 1
minimum: 1
title: Page
type: integer
- in: query
name: limit
required: false
schema:
default: 20
maximum: 100
minimum: 1
title: Limit
type: integer
- description: ISO date; only rows with created_at >= since
in: query
name: since
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: ISO date; only rows with created_at >= since
title: Since
responses:
'200':
content:
application/json:
schema:
additionalProperties: true
title: Response Me Usage Me Usage Get
type: object
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- ApiKeyBearer: []
components:
schemas:
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
ValidationError:
properties:
ctx:
title: Context
type: object
input:
title: Input
loc:
items:
anyOf:
- type: string
- type: integer
title: Location
type: array
msg:
title: Message
type: string
type:
title: Error Type
type: string
required:
- loc
- msg
- type
title: ValidationError
type: object
securitySchemes:
ApiKeyBearer:
description: Your `aeg_…` API key from the dashboard (Account → API tab).
scheme: bearer
type: http
````