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 cost, 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, without pasting transcripts into prompts.

Starting a session or sending it messages needs the organization developer or admin role. See Organizations and roles and API keys. You must be able to read every session you reference, and it must be in the same organization as the session that reads it. References never give an agent access that you do not have. There is no console action to add a reference, so use the API; the console shows references that were added.

Start a session with references

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

cURL

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": "/managed-agents/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.

cURL

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. In the console, open the session and look under Referenced sessions on the Session tab of the details panel.

Reference status events

One new reference reads, for example, “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.

What the agent can read

When a session has at least one reference, its agent gets read-only tools to list the referenced sessions, outline, search, and read their events, and read their team boards, costs, deliverables, and skills. A session with no references does not have them. 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.

Every read tool

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 and teammates: status, stop reasons, event and tool counts, and the tree’s cost.
`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`	The tree’s cost in US dollars: one total for every member’s model calls, tools, and compute.
`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.

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.

How references work

The whole tree is granted. Each id grants the session tree it belongs to: the root session and every subagent and teammate 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.

What can go wrong

The most common problems:

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 with more than 10 ids. One request can name at most 10 sessions. Send the most relevant 10, and start a separate session for the rest.
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.

Every referenced-session error

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

Duplicate ids, or two ids from the same tree, count once. A reference must be in the same organization. The caps of 10 ids per request and 10 session trees held per session are in Limits.

Next steps

Session operations

Send messages, interrupt, and resume sessions.

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

Start a session with references

Add references to a running session

What the agent can read

How references work

What can go wrong

Limits

Next steps

Session operations

Usage and cost

Deliverables and artifacts

​Start a session with references

​Add references to a running session

​What the agent can read

​How references work

​What can go wrong

​Limits

​Next steps

Session operations

Usage and cost

Deliverables and artifacts

Start a session with references

Add references to a running session

What the agent can read

How references work

What can go wrong

Limits

Next steps