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

# Pause, resume, and delete environments

> Pause, resume, and delete an environment, and read its status, time limit, and lifecycle timestamps.

An environment exists as soon as State Machines accepts its creation. Its status describes what it can do now. An accepted environment is not yet ready for app requests.

## Status and data

| Status | Meaning |
| - | - |
| `starting` | The apps are starting. Wait before sending app requests. |
| `running` | The apps can receive requests. |
| `paused` | Compute is released and data remains. Resume before making requests. |
| `failed` | An environment that previously ran could not start or restart. Its data remains available for a resume attempt. It is deleted one day after it failed. |
| `deleted` | The environment has ended and data cleanup proceeds. Its metadata remains readable by ID. |

If an environment fails before it ever runs, State Machines deletes it with reason `failed`. The SDK reports that through `EnvironmentFailedError`.

## Pausing keeps the current data

`pause()` changes the status when the API answers. From then on, the gateway answers app requests with `environment_not_running`. Pausing releases compute and stops the time limit. The environment keeps its data. Pausing a `starting` environment fails with `invalid_status`.

`resume()` starts apps on that same data. The SDK waits for `running` unless you pass `{ wait: false }`. Resuming counts against the organization's concurrent limit and can fail with `environment_limit_reached`. A returned environment object describes one read of the resource. To get its new status, use the object returned by the operation or call `refresh()`.

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

const sm = new StateMachines();
const env = await sm.environments.create(
  { apps: ['salesforce'] },
  { wait: false },
);

try {
  await sm.environments.wait(env.id, { status: 'running' });
  const paused = await env.pause();
  console.log(paused.status);
  const resumed = await env.resume();
  console.log(resumed.status);
  const salesforce = await resumed.connect('salesforce');
  const response = await salesforce.fetch('/services/data/v67.0/limits');

  if (!response.ok) {
    throw new Error(`Salesforce returned ${response.status}`);
  }

  console.log(response.status);
} finally {
  await env.delete();
}
```

## Deleting ends ownership

`delete()` marks the environment deleted and refuses further app access when the API answers. Compute and data cleanup continue after the response. Repeating `delete()` is safe, so call it in an awaited `finally` block. Pause for an interactive break, but delete the environment at the end of a task.

The time limit counts time spent in `starting` and `running`. `sm.me().limits.timeLimitMinutes` returns its default and maximum. State Machines deletes the environment when the time limit ends. State Machines deletes a paused or failed environment one day after it paused or failed, with reason `expired`. `expiresAt` shows that deadline.

A ready snapshot is a separate saved copy. Use [snapshots](/snapshots/create) for reusable data that must outlive the source environment.

## Read lifecycle timestamps

`createdAt` records acceptance. `startedAt` records the first time the environment became running. A resume does not change it. `pausedAt` records when the current paused or failed period began. `expiresAt` is the current deletion deadline and is null once deleted.

A deleted environment's `reason` distinguishes expiration, failure before first startup, and cancellation by staff. A caller-requested deletion has a null reason. If `failure` is present, it names the affected app and gives its code and message.

Pause, resume, and delete are actions. `wait()` only observes. Waiting for `running` on a paused environment does not resume it and fails with `UnexpectedStatusError`. When a resumed app fails, `EnvironmentFailedError` carries the environment for diagnosis. See [SDK errors](/sdk-api/errors) for polling outcomes.

## Cleanup belongs to the caller

An accepted environment keeps running after the caller stops waiting or loses its process. Get the ID with `wait: false` before the work that needs cleanup. Keep an explicit create key when the acceptance response itself could be lost.

An awaited `finally` handles failures while the process is alive. CI cancellation or a runtime crash can prevent it from running. Persist owned environment IDs with the job, use labels to identify the run, and recover cleanup in a later job. The time limit is a final bound, not confirmation that cleanup succeeded.

If deletion fails, keep both the environment ID and the cleanup error, then retry the deletion. Do not reuse an aborted work signal for cleanup, because it cancels the delete request too.


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