# Usage, logs & audit

Three read-only views of what your integration did — the usage chart under **Settings → API** in the portal shows the same numbers.

## Request log

`GET /v1/request-logs` (scope `account:read`): every request of the last **30 days** in the mode of your key, newest first, with `method`, the route template (`/v1/leads/{id}`), `status`, `error_code`, the `key` that made it and `duration_ms`. Filters: `status`, `route`, `key`, `created_since`; pages with `limit`, `starting_after` and `ending_before`.

Requests refused before any work for a limit — `429 rate_limited` and `429 concurrency_limited` — are not logged and not counted in usage; they never counted towards the rate limit either. A request refused with `403 ip_not_allowed` **is** logged and shows in usage, so you can see when one of your keys is used from an address outside its allow-list; it does not count against the rate limit. The log never holds request or response bodies, headers or creator data. The `id` (`req_…`) is the `X-Request-Id` of that request — quote it to [support](https://docs.creator-guard.com/support/).

## Usage

`GET /v1/usage?from=2026-10-01&to=2026-10-30` (scope `usage:read`) counts the requests of your account in the mode of your key, per UTC day (`series`), per route (`by_route`) and per key (`by_key`):

| Field | Meaning |
|---|---|
| `requests` | All requests, every status |
| `errors` | Answers with status 400 or higher; `series[].error_codes` counts them by `code` |
| `p50_ms`, `p95_ms` | Median and 95th percentile of the duration on our side; `null` without requests |

`from` and `to` are dates (UTC), both included, at most 90 days apart. Both are optional: without them you get the last 30 days up to today. `granularity` is `day`.

## Audit trail

`GET /v1/audit-events` (scope `audit:read`): changes to your account in the last **90 days** in the mode of your key, newest first (a live key also sees the changes that concern the whole account, such as your key policy or limits; a test key only test-mode changes) — who (`actor.kind`: `key`, `user`, `admin` or `system`), what (`action`), on what (`target`), from which IP and browser or client, and the changed names and values in `details`. Filters: `action`, `created_since`; pages with `limit`, `starting_after` and `ending_before`.

| `action` | When |
|---|---|
| `api_key.created`, `api_key.rolled`, `api_key.revoked` | A key changed (a revocation by your key policy has actor `system`; keys revoked because their member was removed or got a narrower role name the reason and the member in `details`) |
| `api_key.leaked` | A key turned up in public (for example GitHub secret scanning reported it) and we revoked it at once; actor `system` |
| `key_policy.changed` | Maximum key age or auto-revocation changed |
| `webhook_endpoint.created`, `.updated`, `.deleted`, `.secret_rotated` | A webhook endpoint was created, changed, deleted or got a new secret |
| `webhook_endpoint.tested`, `.replayed`, `.delivery_retried` | A test send, a replay or a retry was started with the API |
| `oauth_app.created`, `.updated`, `.deleted`, `.secret_rolled` | An [OAuth app](https://docs.creator-guard.com/oauth/) was registered, changed, deleted or got a new client secret (a secret replaced because a member was removed or got a narrower role has actor `system`) |
| `oauth_app.secret_leaked`, `oauth_app.token_leaked` | A client secret or a creator's access or refresh token of the app turned up in public (for example GitHub secret scanning) and we replaced the secret (`details.secret`: `current`, or `previous` — then your current secret keeps working) or ended that creator's authorization at once (`details.grant`); actor `system` — see [OAuth](https://docs.creator-guard.com/oauth/) |
| `agreement.accepted` | Terms were accepted through the API |
| `member.invited`, `member.invitation_revoked` | An invitation was sent or revoked — see [Members & roles](https://docs.creator-guard.com/members/) |
| `member.joined`, `member.role_changed`, `member.removed` | Someone accepted an invitation, got another role or was removed |
| `member.login_email_changed` | A member (not the owner) changed the email address of their own login in the portal; the entry names the member and carries no address |
| `account.updated`, `account.logo_updated`, `account.logo_removed` | Your profile or logo changed with the API |
| `sandbox.reset` | The test data was deleted with `POST /v1/test-helpers/reset` |
| `limits.changed` | Creator Guard changed your limits |
| `lead.created_by_admin` | Our team added a creator to your account for you; she is yours like any lead you submit (the `lead.created` webhook fires as usual) |
| `account.mfa_enabled`, `account.mfa_removed` | An authenticator (second factor) was set up or removed — also listed in the portal under **Settings → Login & security**. We send no email about it. |

New actions may be added. `details` never contains a secret or creator data.

## Retention

| Data | Kept |
|---|---|
| Request log | 30 days readable (90 days on our side) |
| Usage | Up to 90 days back |
| Audit trail | 90 days |
| Events and webhook deliveries | 30 days |
