> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Reference prior sessions > Give a session read-only access to earlier sessions so its agent can search their transcripts, costs, grading, and deliverables. 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](/managed-agents/api#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](/managed-agents/organizations-and-roles) and [API keys](/managed-agents/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 ```mermaid theme={"theme":"css-variables"} flowchart LR request["startSession or sendSessionEvents with referenced_session_ids"] --> check["Every id is checked against your access"] check -->|"all readable"| grant["Each id's whole session tree is granted"] check -->|"any id unreadable"| reject["404 not_found, nothing recorded"] grant --> turn["The agent's next turn has the read tools"] turn --> read["Every read checks access again"] ``` * **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 theme={"theme":"css-variables"} 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'], }, }); ``` ```bash theme={"theme":"css-variables"} 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: ```json theme={"theme":"css-variables"} { "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 theme={"theme":"css-variables"} 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'], }, }); ``` ```bash theme={"theme":"css-variables"} 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"] }' ``` ```json theme={"theme":"css-variables"} { "ok": true, "delivery_state": "signaled", "events_accepted": 1 } ``` See [Session operations](/managed-agents/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](/managed-agents/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](/managed-agents/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](/managed-agents/limits). ## Next steps Send messages, interrupt, and resume sessions. Read how earlier sessions were graded. Compare what earlier sessions cost. See which files a session keeps.