# Logs

Every request CLItrail receives for your organisation and every request it sends on your behalf is recorded with its exact body, next to every change your team makes. You can read, filter, trace and export all of it, on every plan.

## What is recorded

| Kind | Recorded for | Contents |
| --- | --- | --- |
| Inbound | Every collection request, `/v1/visits`, `/v1/visits/activate`, `/v1/handoffs` and `/v1/events`, including rejected, rate-limited and malformed ones | The JSON body exactly as received, the method and route, the time, the response status and error code, the website, the browser and system worked out from the request, and the visit or event it created. |
| Outbound | Every delivery attempt to GA4, Google Ads, Meta, TikTok, X Ads and webhooks, every connection test, and every log-stream batch | The exact request body, endpoint, method and headers with credentials redacted, the response status, the response body (up to 64 KB, redacted), the duration, the attempt number and the install events it carried. |
| Audit | Every change to the organisation, its websites, destinations, install paths, members, streams and plan, and every limit reached | Who did it, what changed and when. Never a secret value. |
| Error and alert | Internal failures and notices, such as a quota passing 80% or a log stream failing | A code and a short explanation. |

## What is never recorded

- **Credentials.** Access tokens, API secrets in URLs, `Authorization` headers, signatures and keys appear as `[redacted]`.
- **Receipts and handoff tokens.** They work like passwords for a visit, so the log keeps only a label with their last 6 characters and a keyed hash, such as `receipt …Ab3dE9 #…`.
- **IP addresses.** Only a keyed hash, never the address.

Bodies larger than the 16 KB collection limit are recorded truncated, with the reason they were refused. Outbound bodies over 64 KB are cut there and marked `truncated`.

## Always on

Recording cannot be turned off, for any plan. A request never fails because its record could not be written: the service answers as usual and writes a fallback line to the platform’s own log instead.

## The Logs tab

- **Timeline** of every record, newest first, filtered by kind, route, destination, status, website, time range, or a search on IDs.
- **JSON viewer** for each record, pretty-printed, with copy.
- **Install trace:** one install’s whole story, from the visit and the hook’s report to the match and every delivery attempt, with the bodies.
- **Export** of the filtered range as CSV or NDJSON: up to 100,000 records or 25 MB per file, and 10 exports per organisation an hour.

Everyone in the organisation can read its logs; members and above can export them. On Free, attribution fields are left out of the records, as everywhere else on Free.

## Retention

Records are kept for 30 days by default, or for the plan’s maximum when that is shorter. Admins and owners choose from 7 days up to the plan’s maximum: 7 on Free, 30 on Standard and 90 on Enterprise. Older records are deleted by the regular clean-up. To keep them longer, send them to your own storage with a [log stream](https://clitrail.com/docs/log-streams).

## API

| Endpoint | Returns |
| --- | --- |
| `GET /api/orgs/:org/logs` | A page of records, at most 200, with a cursor for the next. Filters: `kind`, `route`, `destination`, `status`, `website`, `from`, `to`, `q`, `install`, `event`, `cursor`, `limit`. |
| `GET /api/orgs/:org/logs/:id` | One record. |
| `GET /api/orgs/:org/logs/export?format=csv` | A download of the filtered range, `csv` or `ndjson`. |

These are dashboard endpoints, authenticated by your session. Each record’s fields are listed in the [record schema](https://clitrail.com/docs/telemetry-schema).