Reference prior sessions

A referenced session is an earlier session that a new or running session may read. Pass its id in referenced_session_ids, and the agent gets read-only tools to search that session’s transcript, review its spend and grading, and open its deliverables. Use references to debug a failed run, pick up where earlier work stopped, or compare several attempts at the same task. The agent reads the earlier sessions directly, so you do not paste transcripts into prompts. The TypeScript samples assume the rl client from Client setup.

Before you begin

You need the organization developer or admin role to start a session or send it messages. See Organizations and roles and API keys.
You must be able to read every session you reference. References never give an agent access that you do not have.
Referenced sessions must be in the same organization as the session that reads them.
There is no console action to add a reference. Use the API. The console shows references that were added.

How references work

The whole tree is granted. Each id grants the session tree it belongs to: the root session and every subagent, teammate, and grading pass under it. You can pass the id of any session in the tree.
All or nothing. If you cannot read one of the ids, the whole request fails and nothing is recorded: no reference, no message, no new session.
Read-only and live. The agent cannot change a referenced session. It reads current data, so a referenced session that is still running shows its latest events.
Checked on every read. If a referenced session is deleted, or its access is restricted after it was added, the agent’s reads of it stop working.
Inherited, never widened. Subagents and teammates of the reading session can read the same sessions. They cannot add references of their own.
Kept for the session. You can’t remove a specific reference. Once a session holds 10, adding another drops the oldest. To drop a reference on purpose, start a new session.

Start a session with references

Send referenced_session_ids in the start request. The agent can use the read tools from its first turn.

TypeScript
cURL

const { session_id } = await rl.managedAgents.startSession({
  'Idempotency-Key': 'triage-failed-run-2026-09-17',
  body: {
    agent_id: '5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55',
    environment_id: '9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13',
    message:
      'The referenced session failed its test step. Find the first failing command, explain the cause, and propose a fix.',
    referenced_session_ids: ['b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38'],
  },
});

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Idempotency-Key: triage-failed-run-2026-09-17' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
    "environment_id": "9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13",
    "message": "The referenced session failed its test step. Find the first failing command, explain the cause, and propose a fix.",
    "referenced_session_ids": ["b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38"]
  }'

The API answers 202 Accepted with the new session’s id:

{
  "session_id": "e3a1f7c2-9b4d-4e60-8c15-2d7f0a6b9e48",
  "status_path": "/v1/sessions/e3a1f7c2-9b4d-4e60-8c15-2d7f0a6b9e48"
}

Name the task in the message. A reference only makes the earlier session readable; the agent decides what to read based on what you ask.

Add references to a running session

Send referenced_session_ids with a user message on sendSessionEvents. The reference is recorded before the message, so the turn that the message starts can already read it. interruptAndSendSessionMessage accepts the same field.

TypeScript
cURL

await rl.managedAgents.sendSessionEvents({
  session_id: 'e3a1f7c2-9b4d-4e60-8c15-2d7f0a6b9e48',
  body: {
    events: [
      {
        type: 'user.message',
        content: [{ type: 'text', text: 'Compare your fix with the one in the second referenced session.' }],
      },
    ],
    referenced_session_ids: ['0c6f2b9e-4d17-4a38-b5e2-9f1a3c7d8e06'],
  },
});

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a1f7c2-9b4d-4e60-8c15-2d7f0a6b9e48/events' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "Compare your fix with the one in the second referenced session."}]
      }
    ],
    "referenced_session_ids": ["0c6f2b9e-4d17-4a38-b5e2-9f1a3c7d8e06"]
  }'

{
  "ok": true,
  "delivery_state": "signaled",
  "events_accepted": 1
}

See Session operations for delivery_state and the other message options. What success means: the session’s timeline gets a status event that names the new references, such as “This session was given read access to prior session b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38.” A request that adds several says how many, such as “This session was given read access to 2 prior sessions.” Naming a session that is already referenced adds nothing and records no event. In the console, open the session and look under Referenced sessions on the Session tab of the details panel.

What the agent can read

When a session has at least one reference, its agent gets these read-only tools. A session with no references does not have them.

Tool	What it reads
`list_referenced_sessions`	The referenced sessions: each one’s agent, status, and task, when it started, and when it was referenced. Marks any that can no longer be read.
`session_overview`	Every member of the tree, including subagents, teammates, and grading passes: status, stop reasons, event and tool counts, spend, and outcomes.
`session_outline`	A compact timeline of the tree, up to 200 entries (80 by default).
`search_events`	A case-insensitive text search over events, filtered by member session, tool name, or event type. Up to 50 matches (20 by default).
`read_events`	A page of events in order, up to 40 at a time (20 by default).
`get_event`	One event in full, with an offset for reading long content in pieces.
`view_event_images`	An image attached to an event.
`get_team_state`	A team’s shared board and each member’s scratchpad.
`get_costs`	Model spend in US dollars for each member and for the whole tree.
`get_outcomes`	Every outcome, each grading pass, and each criterion’s verdict and reason.
`list_session_files`	The deliverables each member saved and the skills each member used.
`read_session_file`	One deliverable, read in pieces for large files.
`read_session_skill`	A file from a skill that a member used, exactly as that member saw it.

When a session has more than one reference, the agent names the one it wants on each call. list_referenced_sessions gives it the ids.

Referenced transcripts can contain text written by users, tools, and websites. Treat what the agent concludes from them with the same care as any other untrusted input, and only reference sessions whose contents you are willing to show the agent.

What can go wrong

Symptom or code	Cause	Fix
`404 not_found` on `referenced_session_ids`	One of the ids does not exist, is in another organization, or you cannot read it. Nothing was recorded.	Check each id and your API key’s organization. Remove ids you cannot read, then resend.
`400 invalid_request` on `referenced_session_ids`, more than 10 ids	One request can name at most 10 sessions.	Send the most relevant 10. Start a separate session for the rest.
`400 invalid_request` on `referenced_session_ids`, empty id	The list contains an empty string.	Remove it.
`400 invalid_request` on `referenced_session_ids`, the session references itself	A session cannot reference its own tree.	Reference a different session.
`400 invalid_request` on `referenced_session_ids`, other sessions	Session analyst conversations and sessions with restricted access cannot be referenced.	Reference the session you analyzed, not the analyst conversation.
`403 forbidden`	Your role can only read sessions.	See Organizations and roles. Use an account or key with the developer or admin role.
The agent says a reference can no longer be read	The referenced session was deleted, or its access was restricted after it was added.	Start a new session with a different reference.
The agent cannot find an early reference	The session holds at most 10 references. Adding more drops the oldest.	Keep the set small. Start a new session for a different set.
The agent does not have the read tools	The session has no references.	Send `referenced_session_ids` with a message.

The full list of codes is in Errors.

Limits

Limit	Value
Ids in one request	10
References one session holds	10 session trees. Adding more drops the oldest.
Duplicate ids, or two ids from the same tree	Count once.
Organization	Same organization only.

Other limits are on Limits.

Next steps

Session operations

Send messages, interrupt, and resume sessions.

Outcomes

Read how earlier sessions were graded.

Usage and cost

Compare what earlier sessions cost.

Deliverables and artifacts

See which files a session keeps.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Reference prior sessions

Before you begin

How references work

Start a session with references

Add references to a running session

What the agent can read

What can go wrong

Limits

Next steps

Session operations

Outcomes

Usage and cost

Deliverables and artifacts

​Before you begin

​How references work

​Start a session with references

​Add references to a running session

​What the agent can read

​What can go wrong

​Limits

​Next steps

Session operations

Outcomes

Usage and cost

Deliverables and artifacts

Before you begin

How references work

Start a session with references

Add references to a running session

What the agent can read

What can go wrong

Limits

Next steps