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

# Runs: your sessions, and the ones that need you

> Runs lists every session in your organisation, with the ones waiting on a person first. Starting a session from it is not available yet.

Runs is the first screen you land on.
It lists every session in your organisation, with the ones waiting on you above everything else.
At the top is the box a session is started from.

## Starting a session is not available yet

The box at the top of Runs is there, and it is switched off.
The text area, the repository menu under it and **Start session** are all greyed out, and the line under the box reads **Sessions cannot be started yet.**
Nothing on the screen changes that, and it is the same for every member and admin of every organisation.

If no repository is connected, Runs says **Connect a repository first** instead of showing the box.
If repositories are connected but all of them are disabled, it says **No repository can be reached**.
Either way, ask an admin of your organisation: [connecting a repository](/guides/connecting-a-repository) can be done today, takes a few minutes and needs one.
If the repositories cannot be loaded at all, you get the reason and a **Try again** button in place of the box.

Once a repository is connected, the list reads **No sessions yet** until sessions can be started.

## Sessions waiting on you come first

The rest of this page describes the list as it reads once it holds sessions.

Two kinds of session need a person.

* **Paused** sessions stopped because something has to be decided.
  The row says why, in words, under the title.
  When no reason was recorded it says *No reason was given.*
* **Ready for review** sessions have finished and are waiting for you to look.

Both sit above everything else.
Inside each group, and in the rest of the list, the newest session is first.

The number beside **Runs** in the navigation counts every paused or ready-for-review session in your organisation, whoever started it.
It does not change when you filter the list, and it disappears when nothing is waiting.
Above 99 it reads **99+**.

## What each status means

| Status | What it means |
| - | - |
| **Setting up** | The session has been accepted and its environment is being prepared |
| **Running** | The agent is working |
| **Idle** | The agent finished a turn and its environment is asleep for now |
| **Waking** | A sleeping environment is starting again for a message that waits |
| **Paused** | A key failed or a limit was reached, and it waits on you |
| **Ready for review** | The agent has finished and is waiting for you to look |
| **Published** | A pull request is open |
| **Stopped** | The session was stopped and cannot start again |
| **Failed** | Something went wrong and the session ended |

Each row also shows the repository and the time the session was started, in your browser's time zone.

## The list keeps itself up to date

Leave Runs open and it asks for the list again every few seconds, and less often once you have loaded more than two pages.
When a session's status changes, its row changes in place, with no reload and nothing to press.
While the tab is in the background it waits, and it catches up when you come back.

If a refresh fails, the list you had stays on screen and a line above it says **These may be out of date. The last refresh failed.**
It tries again on its own.
If the list cannot be loaded at all, you get the reason and a **Try again** button.

## Narrowing the list

Two menus sit above the list.

* **Status** shows one status, or all of them.
* **Repository** shows the sessions of one connected repository, or all of them.

They combine, and **Clear filters** appears when nothing matches.
The list loads 25 sessions at a time, and **Load more** fetches the next 25.
Your choice of filters is for this visit only and is not kept when you leave the page.

## From the API

These calls are available to any member of the organisation and need a signed-in session, as in [your first API call](/guides/your-first-api-call).

List sessions, waiting ones first:

```bash theme={null}
curl -s "https://api.scaling.cloud/sessions?status=paused&limit=25" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

| Parameter | What it does |
| - | - |
| `status` | Only sessions in this status: `provisioning`, `running`, `idle`, `waking`, `paused`, `ready_for_review`, `published`, `stopped` or `failed` |
| `projectId` | Only sessions of this repository |
| `limit` | Page size, from 1 to 50. The default is 25 |
| `cursor` | The `nextCursor` of the previous page. Absent on the first page |

```json Response theme={null}
{
  "sessions": [
    {
      "id": "01JB2Z...",
      "title": "Rename billing settings",
      "projectId": "01JB2Y...",
      "origin": "prompt",
      "status": "paused",
      "startedByUserId": "user_01JB2X...",
      "pullRequestUrl": null,
      "paused": { "reason": "usage_cap", "detail": "The session reached its token cap." },
      "createdAt": "2026-10-04T10:00:00.000Z",
      "updatedAt": "2026-10-04T10:12:00.000Z"
    }
  ],
  "waiting": 1,
  "nextCursor": null
}
```

`waiting` counts every session waiting on a person, whatever the page was filtered to.
`nextCursor` is `null` on the last page.

Starting a session from the API is not available yet either.
`POST /sessions` answers `403` with code `forbidden` and the message *Sessions cannot be started yet.*, whatever is sent and whoever sends it.

To check from a program, read `canStartSessions` on the projects list:

```bash theme={null}
curl -s https://api.scaling.cloud/projects \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

It is `false` while sessions cannot be started.

Read one session, as it is now:

```bash theme={null}
curl -s https://api.scaling.cloud/sessions/01JB2Z... \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

It answers with the same session shape as the list, or `404` with code `not_found` when the session is not your organisation's.
See [the error shape](/api-reference/introduction) for the rest.


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