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

# Sessions

> A session is one pairing code and its invite link, for one customer's computer.

A session connects one computer to your org. You create it with `POST /v1/sessions`, send its `invite_url` to the customer, and once their computer is connected you run tasks on it. Think of it as a call: it has one other party, a status, and a history of what happened.

## Codes

Each session has a pairing code such as `K7QM-24XP`: two groups of four characters from `A`–`Z` and `2`–`9`. The code is the session's id: `session_id` and `code` are the same value, and it goes in URL paths like `/v1/sessions/K7QM-24XP`. Codes are not case-sensitive, and the dash is optional.

A code is a short-lived invitation, not a secret credential for your API: everything in `/v1` still needs your API key. Treat the invite link like any support link you send a customer.

## Statuses

| `status`       | Meaning                                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `waiting`      | No computer has used the code yet.                                                                                                                      |
| `connected`    | Its computer is online now. You can start tasks.                                                                                                        |
| `disconnected` | A computer paired with the code but isn't online now (the app was quit, the computer slept, the network dropped). It reconnects on its own when it can. |
| `expired`      | The code went unused for 72 hours and no computer is connected. It can't be used again; make a new session.                                             |

```mermaid theme={null}
stateDiagram-v2
    [*] --> waiting: POST /v1/sessions
    waiting --> connected: customer clicks Connect
    connected --> disconnected: app quit, sleep, network
    disconnected --> connected: app reconnects
    waiting --> expired: 72 hours unused
    disconnected --> expired: 72 hours unused
```

`expires_at` is when the code will expire if nothing else happens. It is `null` while the computer is connected, and moves forward with each use (`last_active_at`). `paired_at` is when a computer first connected.

To know when the computer connects, poll `GET /v1/sessions/{session_id}` or subscribe to the `session.connected` and `session.disconnected` [webhooks](/guides/webhooks).

## One computer per code

The first computer that connects with a code owns it. Another computer trying the same code is refused with "This code is already paired with another device." The same computer can reconnect as often as it needs to, for example after a restart. To help a second computer, create a second session.

When connected, `device` describes the computer:

```json theme={null}
{
  "os": "mac",
  "name": "Dana's MacBook Air",
  "width": 1470,
  "height": 956,
  "app_version": "1.8.0"
}
```

`os` is `mac`, `windows`, `linux` or `unknown`. The desktop app runs on macOS and Windows.

## What the customer sees

1. **The invite page.** Your agent's greeting, then a guided download and install for their operating system. The page knows when the app on their computer has the code filled in.
2. **Permissions (macOS only).** macOS needs Accessibility and Screen Recording for GuidingHand. The app shows exactly which switches to turn on in System Settings. Windows needs no extra permissions.
3. **Connect.** The invite link can fill in the code, but connecting always takes the customer's own click.
4. **While a task runs.** An always-on-top banner with a **Stop** button, and the agent's own red pointer moving on their screen so they can see what it is doing. Unless the agent turns them off, the banner also shows the agent's thoughts and steps as it works, and its questions and approval requests, which the customer can answer or decide right there. See [what the customer sees and answers](/concepts/agents#on-the-customers-screen).

The customer can stop the agent at any time:

* the **Stop** button on the banner, or
* the shortcut <kbd>⌘</kbd> <kbd>⇧</kbd> <kbd>Esc</kbd> on macOS, <kbd>Ctrl</kbd> <kbd>Alt</kbd> <kbd>Shift</kbd> <kbd>S</kbd> on Windows.

The task then ends with status `stopped` and a `stopped` event whose message is "Stopped by the person at the computer." Plan for this: the customer is always in control, and a stopped task is a normal outcome, not an error.

The customer never needs a GuidingHand account.

## Metadata

`metadata` is your own key-value data (for example a ticket or customer id), returned as given on the session and in webhooks. Up to 50 keys; keys up to 40 characters; values must be strings up to 500 characters.

```json theme={null}
{ "agent_id": "billing", "metadata": { "ticket_id": "T-1042", "customer_id": "cus_42" } }
```

## Listing and deleting

* `GET /v1/sessions` lists sessions newest first, optionally filtered by `agent_id`. Each has `task_count` and `latest_task_id`. See [pagination](/guides/errors#pagination).
* `DELETE /v1/sessions/{session_id}` disconnects the computer, stops a running task, and deletes the session's tasks, events and recordings for good. It needs the admin role or an API key.

<Warning>
  Deleting a session can't be undone. Its tasks, events and recordings are gone, including their replays in the console.
</Warning>