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

# Runners & Apps API

> See which apps and runners are live right now - they appear because a runner registered itself, with its self-reported metadata attached.

The read-only runners and apps API backs the console's **Apps** view. It reflects **live
registrations** - apps and runners appear because a runner registered, not because anything was
configured by hand. There is no write surface here: runners register themselves through the SDK
handshake (see [runners](/core/runners)).

| Method + path  | Returns                                                                |
| -------------- | ---------------------------------------------------------------------- |
| `GET /apps`    | The project's registered apps.                                         |
| `GET /runners` | The project's registered runner endpoints, with metadata and liveness. |

## GET /apps

Lists every app that has registered in the project, ordered by name.

| Field       | Meaning                                 |
| ----------- | --------------------------------------- |
| `name`      | The app name.                           |
| `createdAt` | When the app was first seen (ISO 8601). |

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { createClient } from "@duraton/sdk/client";

    const duraton = createClient({ url: process.env.DURATON_URL! });
    const apps = await duraton.apps.list(); // App[]
    ```
  </Tab>

  <Tab title="REST API">
    ```sh theme={null}
    curl $DURATON_URL/apps
    ```
  </Tab>
</Tabs>

## GET /runners

Lists the registered runner endpoints. Pass `?app=<name>` to scope to one app; omit it for every app
in the project.

| Param | Meaning              | Default  |
| ----- | -------------------- | -------- |
| `app` | Restrict to one app. | all apps |

Each runner carries the metadata it reported on register. Optional fields are present only when the
runner actually reported them (a runner predating a field, or one that left it unset, omits it).

| Field                 | Meaning                                                                                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runnerId`            | The runner's stable id, or its URL when it registered without one.                                                                                                                      |
| `app`                 | The app this runner hosts.                                                                                                                                                              |
| `url`                 | A `conn://` pseudo-URL naming the runner's WebSocket connection.                                                                                                                        |
| `framework`           | `connect`.                                                                                                                                                                              |
| `runtime`             | The JS runtime: `node`, `bun`, or `deno`.                                                                                                                                               |
| `sdkName` + `version` | The SDK package and version.                                                                                                                                                            |
| `region`              | The deployment region, when `DURATON_REGION` is set.                                                                                                                                    |
| `lastSeenAt`          | When Duraton last saw this runner (ISO 8601): its last socket heartbeat. It advances roughly every `30s` while the runner is healthy.                                                   |
| `live`                | Whether `lastSeenAt` is inside the `90s` liveness window, so a runner whose process is gone reports `live: false` once it falls behind. A runner past the window is listed, not hidden. |

See [runner liveness](/core/runners#liveness) for what refreshes `lastSeenAt`, and what a `live: false` runner means for routing.

Responses never include a key or secret.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { createClient } from "@duraton/sdk/client";

    const duraton = createClient({ url: process.env.DURATON_URL! });
    const runners = await duraton.runners.list({ app: "shop" }); // Runner[]
    ```
  </Tab>

  <Tab title="REST API">
    ```sh theme={null}
    curl "$DURATON_URL/runners?app=shop"
    ```
  </Tab>
</Tabs>

```json theme={null}
[
  {
    "runnerId": "gateway-1",
    "app": "shop",
    "url": "conn://01HXYZ...",
    "framework": "connect",
    "runtime": "node",
    "sdkName": "@duraton/sdk",
    "version": "0.1.0",
    "region": "us-east-1",
    "lastSeenAt": "2026-06-25T10:30:00Z",
    "live": true
  }
]
```