> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usestatemachines.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests and audit events

> Interpret recorded app traffic, body coverage, statistics, and audit events.

Requests record calls through the app gateway. Audit events record State Machines resource actions. Both require `environments:read`, including access to stored request and response bodies. API keys can read records only in their own workspace.

## Recorded requests

`sm.requests.list({ environmentId })` returns recorded calls, newest first. Each record identifies the app, method, path, query, status, duration, and timestamps. `respondedBy` identifies `app` or `gateway`. `errorCode` is present when the gateway answered with an error.

The gateway does not guarantee that it records every request. Recorder capacity or storage failures can leave gaps. Some failures occur before an authenticated request can be recorded. Neither the list nor its statistics is a complete transaction ledger.

The request list accepts these filters:

| Filter | Meaning |
| - | - |
| `environmentId` | Required environment ID. |
| `app` | App name within the environment. |
| `method` | Exact HTTP method. |
| `responseStatus` | Exact HTTP response status. |
| `statusClass` | `2xx`, `3xx`, `4xx`, or `5xx`. |
| `writesOnly` | Methods `POST`, `PUT`, `PATCH`, and `DELETE`. A match does not show that a write succeeded. |
| `search` | Case-insensitive text search in the path, query, and recorded searchable text bodies. Requires `from` and `to`. |
| `from`, `to` | SDK `Date` values supplied together, with `to` after `from`. The start is inclusive and the end exclusive. |

A window can span at most 7 days. The API rejects an invalid window with `invalid_request`. Narrow the window to the failing run.

Filters combine, so an exact status outside the chosen status class produces no results. A page cursor belongs to its original filters. After changing filters, request a new first page. Omitted bodies and redacted values cannot be recovered through search.

## Request details and bodies

`sm.requests.get(id)` adds selected headers and body metadata. The request and response have separate coverage values:

| Coverage | Meaning |
| - | - |
| `recorded` | The recorder stored the body. |
| `redacted` | The stored body replaces recognized sensitive fields. |
| `omitted` | No body was stored. `reason` explains why when it is known. |

`encoding` is `utf8` or `binary`. A binary body has no text preview. `previewTruncated` means the preview holds only the first 8 KiB of the stored body. The dashboard fetches the remaining stored text when it opens a truncated text body.

`sm.requests.body(id, 'request')` and `sm.requests.body(id, 'response')` return stored bytes as `Uint8Array`. The result preserves recording redactions. An omitted body returns `not_found`, even when the request record exists. Downloads cannot restore omitted content or credentials.

The recorder stores selected headers, not every original header. It omits authentication headers and cookies. See [credentials and recorded data](/environments/security) for handling guidance.

## Request statistics

`sm.requests.stats({ environmentId, from, to })` requires SDK `Date` values for both ends of the window. It accepts the same app, method, status, write, and search filters as the list.

The response includes counts, latency percentiles, and time buckets for recorded calls. `successCount` includes statuses below `400`, including redirects. These HTTP outcomes do not establish whether a business operation succeeded. Latency percentiles are null when there are no matching calls.

```ts theme={null}
import { type StateMachines, StateMachinesError } from '@usestatemachines/sdk';

export async function inspectRecordedRequests(
  sm: StateMachines,
  environmentId: string,
  from: Date,
  to: Date,
) {
  const filters = { environmentId, from, to };
  const stats = await sm.requests.stats(filters);
  console.log('Recorded requests:', stats.count);
  let cursor: string | undefined;

  do {
    const page = await sm.requests.list({ ...filters, cursor });

    for (const request of page.data) {
      const detail = await sm.requests.get(request.id);
      console.log(detail.id, detail.responseStatus, detail.respondedBy);

      if (detail.responseBody.coverage === 'omitted') {
        continue;
      }

      try {
        const bytes = await sm.requests.body(detail.id, 'response');
        console.log('Stored response bytes:', bytes.byteLength);
      } catch (error) {
        if (
          !(error instanceof StateMachinesError) ||
          error.code !== 'not_found'
        ) {
          throw error;
        }

        console.log('No stored response body:', detail.id);
      }
    }

    cursor = page.nextCursor ?? undefined;
  } while (cursor !== undefined);
}
```

## Audit events

`sm.auditEvents.list({ environmentId })` returns the environment's audit events. `sm.auditEvents.list({ workspaceId })` returns the workspace's audit events. An API key can omit `workspaceId` to read its own workspace's audit events. If both IDs are supplied, the environment must belong to that workspace.

Events include a name, principal, subject ID, occurrence time, event data, and a management request ID when one exists. The principal identifies a member, API key, or the system. Examples include `environment.paused`, `environment.deleted`, `credentials.created`, and `snapshot.ready`.

An environment lifecycle event can explain why app requests stopped. A `credentials.created` event records issuance, not every later use of those credentials. A management request ID links events to a management call. It is not an app request record ID.

Deleting an environment removes its app data. Recorded requests and audit events are kept separately from the environment. Recorded bodies can contain test data after the environment ends. These records are not a replacement for a saved snapshot or an archive with a promised retention period.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.