Skip to main content

​
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: 
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: 
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: 
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.