Requests and audit events - State Machines

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 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.

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.

​Recorded requests

​Request details and bodies

​Request statistics

​Audit events

Recorded requests

Request details and bodies

Request statistics

Audit events