---
title: "AppPreviewSession"
description: "The `AppPreviewSession` entity."
section: "Reference"
group: "Types"
order: 29
---

## Definition

```ts
interface AppPreviewSession {
  id: string;
  workspaceId: string;
  appId: string;
  versionId: string;
  status:
    | "failed"
    | "hydrating"
    | "installing"
    | "starting"
    | "ready"
    | "stopped";
  previewUrl: string | null;
  error: string | null;
  metadata: Record<string, unknown> | null;
  lastHeartbeatAt: string;
  createdBy: string | null;
  startedAt: string | null;
  readyAt: string | null;
  stoppedAt: string | null;
  createdAt: string;
}
```

## Fields

| Field             | Type                                                                            | Notes                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `id`              | `string`                                                                        | `readonly` `required`                                                                                   |
| `workspaceId`     | `string`                                                                        | `required` — Workspace that owns the previewed app.                                                     |
| `appId`           | `string`                                                                        | `required` — App being previewed.                                                                       |
| `versionId`       | `string`                                                                        | `required` — App version running inside the preview sandbox.                                            |
| `status`          | `"failed" \| "hydrating" \| "installing" \| "starting" \| "ready" \| "stopped"` | `required` — Sandbox lifecycle: hydrating → installing → starting → ready; terminal 'failed'/'stopped'. |
| `previewUrl`      | `string \| null`                                                                | `required` — Public preview URL once the sandbox is ready.                                              |
| `error`           | `string \| null`                                                                | `required` — Error message when status is 'failed', otherwise null.                                     |
| `metadata`        | `Record<string, unknown> \| null`                                               | `required` — Free-form sandbox metadata (container id, ports, etc.).                                    |
| `lastHeartbeatAt` | `string`                                                                        | `required` — ISO-8601 timestamp of the last keep-alive ping from the sandbox.                           |
| `createdBy`       | `string \| null`                                                                | `required` — User who started the preview; null for system-initiated sessions.                          |
| `startedAt`       | `string \| null`                                                                | `required` — ISO-8601 timestamp when the sandbox boot began.                                            |
| `readyAt`         | `string \| null`                                                                | `required` — ISO-8601 timestamp when the preview URL first became reachable.                            |
| `stoppedAt`       | `string \| null`                                                                | `required` — ISO-8601 timestamp when the sandbox was torn down.                                         |
| `createdAt`       | `string`                                                                        | `readonly` `required` — ISO-8601 timestamp of creation.                                                 |