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

# How sessions work

> Understand the label-to-UUID model, how sessions persist state across CLI commands and Claude Code conversations, and when sessions expire.

# How sessions work

Sessions are the mechanism that lets you build on a prior search instead of starting over. This page explains the model behind them so you can use sessions confidently and understand what to expect.

***

## The two-layer model

Sessions have two layers:

1. **A UUID** — a server-side identifier that Landbase uses to associate your requests with a conversation thread. This is what actually persists state.
2. **A label** — a short, human-readable alias you assign (e.g. `uk-saas`, `acme-research`). This lives in `~/.landbase/sessions.json` on your machine.

When you run:

```bash theme={null}
landbase-cli "narrow to 50-200 employees" --session=uk-saas
```

The CLI looks up `uk-saas` in `~/.landbase/sessions.json`, finds the UUID that was assigned when you first used that label, and sends the UUID to the API. The Landbase backend sees the UUID and understands this request is a continuation of the prior conversation.

If you use a label for the first time, the server creates a new session UUID and the CLI saves the label → UUID mapping locally.

***

## What state persists server-side

The server keeps track of:

* The query history for the session — what you asked before
* The audience context — the companies or people the prior query produced
* Refinement history — what filters you applied in follow-up queries

This means follow-up prompts do not need to repeat the original criteria. "Narrow to 50-200 employees" works because the server knows you are refining "SaaS companies in London" from the prior query.

***

## Labels are local; UUIDs are global

Your labels are stored in `~/.landbase/sessions.json` on your machine only. If you run the same label on a different machine, it will create a new session (a new UUID). The label-to-UUID mapping does not sync across machines.

If you want to continue a session on a different machine, you can pass the raw UUID directly:

```bash theme={null}
landbase-cli "narrow to 50-200 employees" --session=ses_abc123xyz
```

The raw UUID is visible in any search response's `session_id` field.

***

## Sessions in Claude Code

When you run landbase-cli through Claude Code, the environment variable `CLAUDE_CODE_SESSION_ID` is automatically set. The CLI records this alongside your session label for telemetry purposes. From a usage perspective, sessions work identically — pass `--session=<label>` in Claude Code tool calls just as you would in the terminal.

***

## Session lifetime

Sessions do not expire based on a fixed clock. A session remains accessible as long as the underlying data is retained on the Landbase backend. In practice, sessions from recent runs (the past several months) are reliably accessible.

If a session UUID is no longer found on the backend, the next request using that label will start a fresh session, and the CLI will update `~/.landbase/sessions.json` with the new UUID.

***

## Inspecting sessions

To see what happened in a session:

```bash theme={null}
landbase-cli runs list --session=uk-saas
```

Each run shows the prompt, timestamp, and dataset created. This is useful for retracing a research thread or picking up where you left off.

***

## Related

* [How to use sessions](/docs/how-to/use-sessions) — practical guide with examples
* [runs reference](/docs/reference/runs) — full reference for the `runs` command