# trails-api

## Pages

- [Trails API](https://docs.ezghcloud.com/trails-api/index.md) — An organization's Trails: CloudTrail-shaped records of what was done through EZGH Cloud's public APIs (LookupEvents, GetEvent), and Trails Query, SQL over them (StartQuery and the rest). Every path under /v1/organizations/{orgId} is authorized through IAM, with the action in x-ezgh-action (or any of x-ezgh-actions).
- [Get one event](https://docs.ezghcloud.com/trails-api/events/GetEvent/index.md)
- [Search the organization's Trails, newest first](https://docs.ezghcloud.com/trails-api/events/LookupEvents/index.md) — Without `from`, the last 7 days. Unknown parameters are 400. A search that reads too much is 400 lookup_too_broad: narrow the window or add filters.
- [Cancel a query](https://docs.ezghcloud.com/trails-api/queries/CancelQuery/index.md) — 409 query_finished when it has already succeeded, failed or been cancelled.
- [Get a query's status (poll it until it finishes)](https://docs.ezghcloud.com/trails-api/queries/GetQuery/index.md)
- [Read a succeeded query's rows: a page, or a download](https://docs.ezghcloud.com/trails-api/queries/GetQueryResults/index.md) — With Accept: text/csv or application/x-ndjson, every stored row (up to 100 000) as a download. 409 query_not_finished (with Retry-After), query_failed (with reason) or query_cancelled; 410 results_expired 7 days after it finished. Pages and downloads are rate limited per organization (429 too_many_requests, with Retry-After).
- [The trails table's columns, and the functions queries may use](https://docs.ezghcloud.com/trails-api/queries/GetQuerySchema/index.md)
- [The organization's query history, newest first](https://docs.ezghcloud.com/trails-api/queries/ListQueries/index.md) — Everyone's with audit.queries.list; with only audit.queries.get, your own.
- [Start a query](https://docs.ezghcloud.com/trails-api/queries/StartQuery/index.md) — Validates the SQL (400 invalid_query, with line and column) and queues it; a worker runs it. 429 too_many_queries (with Retry-After) when the organization's queue, or everyone's, is full; 429 quota_exceeded (with quota, never Retry-After) when an hourly quota is spent. With an Idempotency-Key, retrying the same request within 24 hours answers the first 202 again, with Idempotent-Replayed: true, and queues nothing; the same key with a different request is 409 idempotency_conflict, and while the first is still being admitted, 409 idempotency_in_progress (with Retry-After).
- [Error](https://docs.ezghcloud.com/trails-api/schemas/Error/index.md) — Every non-2xx answer. Clients branch on code, never on message.
- [EventList](https://docs.ezghcloud.com/trails-api/schemas/EventList/index.md) — A page of events, newest first.
- [Query](https://docs.ezghcloud.com/trails-api/schemas/Query/index.md) — A Trails Query.
- [QueryColumn](https://docs.ezghcloud.com/trails-api/schemas/QueryColumn/index.md) — A result column.
- [QueryError](https://docs.ezghcloud.com/trails-api/schemas/QueryError/index.md) — Why a query failed.
- [QueryList](https://docs.ezghcloud.com/trails-api/schemas/QueryList/index.md) — A page of the query history, newest first.
- [QueryResults](https://docs.ezghcloud.com/trails-api/schemas/QueryResults/index.md) — A page of a succeeded query's rows.
- [QuerySchema](https://docs.ezghcloud.com/trails-api/schemas/QuerySchema/index.md) — The `trails` table's columns and the functions queries may use.
- [QueryStarted](https://docs.ezghcloud.com/trails-api/schemas/QueryStarted/index.md) — A query that's been queued. `Location` names it; poll it until it finishes.
- [QueryStats](https://docs.ezghcloud.com/trails-api/schemas/QueryStats/index.md) — What a query read and returned.
- [QuotaExceeded](https://docs.ezghcloud.com/trails-api/schemas/QuotaExceeded/index.md) — quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
- [SchemaColumn](https://docs.ezghcloud.com/trails-api/schemas/SchemaColumn/index.md) — A column of `trails`.
- [SchemaFunction](https://docs.ezghcloud.com/trails-api/schemas/SchemaFunction/index.md) — A function queries may use.
- [SessionContext](https://docs.ezghcloud.com/trails-api/schemas/SessionContext/index.md) — How the caller signed in.
- [StartQueryRequest](https://docs.ezghcloud.com/trails-api/schemas/StartQueryRequest/index.md) — StartQuery's body: SQL over the `trails` table, in a window of at most 90 days (the last 7
days by default).
- [TrailEvent](https://docs.ezghcloud.com/trails-api/schemas/TrailEvent/index.md) — A Trails event, as recorded, plus `region`.
- [TrailResource](https://docs.ezghcloud.com/trails-api/schemas/TrailResource/index.md) — A resource the call touched.
- [UserIdentity](https://docs.ezghcloud.com/trails-api/schemas/UserIdentity/index.md) — Who made the call.
- [events](https://docs.ezghcloud.com/trails-api/tags/events/index.md) — Reading Trails.
- [queries](https://docs.ezghcloud.com/trails-api/tags/queries/index.md) — Trails Query: SQL over the organization's Trails, run asynchronously.
- [session](https://docs.ezghcloud.com/trails-api/tags/session/index.md) — Who's signed in.