Get root timeline events

curl --request GET \
  --url https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "events": [
    {
      "actor": "human:api",
      "agent_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "cache_read_tokens": 1,
      "cache_write_tokens": 1,
      "causal_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "content": {
        "blocks": [
          {
            "byte_size": 1,
            "content": [],
            "context": "example",
            "data": "example",
            "encrypted_content": "example",
            "height": 1,
            "id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
            "input": {
              "key": "example"
            },
            "is_error": true,
            "media_type": "example",
            "name": "example-name",
            "omitted_bytes": 1,
            "payload": "example",
            "provider": "example",
            "provider_payload": "example",
            "redacted": true,
            "semantic_hint": "example",
            "sha256": "example",
            "signature": "example",
            "source": {
              "file_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
              "type": "file"
            },
            "summary": [],
            "text": "example",
            "title": "example",
            "tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
            "type": "example",
            "uri": "example",
            "url": "https://example.com",
            "url_expires_at": "2026-02-18T09:30:00.000Z",
            "width": 1
          }
        ],
        "evaluation_budget_reached": {
          "affected_target_session_ids": [
            "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
          ],
          "max_tree_cost_usd": "example"
        },
        "evaluation_plan_frozen": {
          "criteria": [
            {
              "criterion_key": "example",
              "criterion_text": "example"
            }
          ],
          "max_concurrent_threads": 1,
          "max_tree_cost_usd": "example",
          "targets": [
            {
              "snapshot_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
              "target_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
            }
          ]
        },
        "evaluation_run_finished": {
          "failure_code": "plan_failed",
          "failure_message": "example",
          "targets_budget_reached": 1,
          "targets_skipped": 1,
          "targets_total": 1,
          "terminal_status": "completed",
          "verdicts_recorded": 1
        },
        "evaluation_target_skipped": {
          "child_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "reason": "example",
          "reason_code": "child_create_failed",
          "snapshot_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "target_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
        },
        "evaluation_target_started": {
          "child_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "clone_state": "ready",
          "evaluation_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "sandbox_provider": "example",
          "snapshot_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "target_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
        },
        "evaluation_verdict_recorded": {
          "child_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "cost_completeness": "complete",
          "cost_usd": "example",
          "evaluation_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "failed_criterion_keys": [
            "example"
          ],
          "result": "pass",
          "snapshot_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "target_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
        },
        "metadata": {
          "key": "example"
        },
        "plan": [
          {
            "content": "example",
            "id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
            "status": "example"
          }
        ],
        "stop_reason": "example",
        "tools": [
          {
            "description": "example",
            "input_schema": {
              "key": "example"
            },
            "name": "example-name"
          }
        ],
        "usage": {
          "cache_read_tokens": 1,
          "cache_write_tokens": 1,
          "cost_usd": 1.5,
          "input_tokens": 1,
          "output_tokens": 1
        }
      },
      "content_hydration_status": "hydrated",
      "content_payload_bytes": 1,
      "content_payload_ref": "example",
      "content_payload_sha256": "example",
      "content_ref": "example",
      "cost_micros": 1,
      "created_at": "2026-02-18T09:30:00.000Z",
      "environment_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "event_status": "example",
      "event_type": "example",
      "finish_reason": "example",
      "inference_config": {
        "max_tokens": 1,
        "provider_params": {
          "key": "example"
        },
        "reasoning_effort": "example",
        "temperature": 1.5,
        "top_p": 1.5
      },
      "input_tokens": 1,
      "latency_ms": 1,
      "model": {
        "base_url": "https://example.com",
        "capabilities": {
          "key": "example"
        },
        "context_window": 1,
        "max_output_tokens": 1,
        "metadata": {
          "key": "example"
        },
        "model": "example",
        "model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
        "model_version": "example",
        "provider": "example",
        "provider_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
        "provider_type": "example",
        "serving_backend": "example"
      },
      "model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "organization_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "output_tokens": 1,
      "parent_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "prompt_tokens": 1,
      "provider_model_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "provider_request_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "provider_type": "example",
      "role": "user",
      "sandbox_instance_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "schema_version": 1,
      "session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "thread_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "tool_name": "example",
      "tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "turn_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
    }
  ],
  "next_page_token": "example"
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {}
}

GET

managed-agents

sessions

{session_id}

events

Get root timeline events

curl --request GET \
  --url https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "events": [
    {
      "actor": "human:api",
      "agent_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "cache_read_tokens": 1,
      "cache_write_tokens": 1,
      "causal_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "content": {
        "blocks": [
          {
            "byte_size": 1,
            "content": [],
            "context": "example",
            "data": "example",
            "encrypted_content": "example",
            "height": 1,
            "id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
            "input": {
              "key": "example"
            },
            "is_error": true,
            "media_type": "example",
            "name": "example-name",
            "omitted_bytes": 1,
            "payload": "example",
            "provider": "example",
            "provider_payload": "example",
            "redacted": true,
            "semantic_hint": "example",
            "sha256": "example",
            "signature": "example",
            "source": {
              "file_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
              "type": "file"
            },
            "summary": [],
            "text": "example",
            "title": "example",
            "tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
            "type": "example",
            "uri": "example",
            "url": "https://example.com",
            "url_expires_at": "2026-02-18T09:30:00.000Z",
            "width": 1
          }
        ],
        "evaluation_budget_reached": {
          "affected_target_session_ids": [
            "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
          ],
          "max_tree_cost_usd": "example"
        },
        "evaluation_plan_frozen": {
          "criteria": [
            {
              "criterion_key": "example",
              "criterion_text": "example"
            }
          ],
          "max_concurrent_threads": 1,
          "max_tree_cost_usd": "example",
          "targets": [
            {
              "snapshot_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
              "target_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
            }
          ]
        },
        "evaluation_run_finished": {
          "failure_code": "plan_failed",
          "failure_message": "example",
          "targets_budget_reached": 1,
          "targets_skipped": 1,
          "targets_total": 1,
          "terminal_status": "completed",
          "verdicts_recorded": 1
        },
        "evaluation_target_skipped": {
          "child_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "reason": "example",
          "reason_code": "child_create_failed",
          "snapshot_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "target_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
        },
        "evaluation_target_started": {
          "child_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "clone_state": "ready",
          "evaluation_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "sandbox_provider": "example",
          "snapshot_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "target_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
        },
        "evaluation_verdict_recorded": {
          "child_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "cost_completeness": "complete",
          "cost_usd": "example",
          "evaluation_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "failed_criterion_keys": [
            "example"
          ],
          "result": "pass",
          "snapshot_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "target_session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
        },
        "metadata": {
          "key": "example"
        },
        "plan": [
          {
            "content": "example",
            "id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
            "status": "example"
          }
        ],
        "stop_reason": "example",
        "tools": [
          {
            "description": "example",
            "input_schema": {
              "key": "example"
            },
            "name": "example-name"
          }
        ],
        "usage": {
          "cache_read_tokens": 1,
          "cache_write_tokens": 1,
          "cost_usd": 1.5,
          "input_tokens": 1,
          "output_tokens": 1
        }
      },
      "content_hydration_status": "hydrated",
      "content_payload_bytes": 1,
      "content_payload_ref": "example",
      "content_payload_sha256": "example",
      "content_ref": "example",
      "cost_micros": 1,
      "created_at": "2026-02-18T09:30:00.000Z",
      "environment_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "event_status": "example",
      "event_type": "example",
      "finish_reason": "example",
      "inference_config": {
        "max_tokens": 1,
        "provider_params": {
          "key": "example"
        },
        "reasoning_effort": "example",
        "temperature": 1.5,
        "top_p": 1.5
      },
      "input_tokens": 1,
      "latency_ms": 1,
      "model": {
        "base_url": "https://example.com",
        "capabilities": {
          "key": "example"
        },
        "context_window": 1,
        "max_output_tokens": 1,
        "metadata": {
          "key": "example"
        },
        "model": "example",
        "model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
        "model_version": "example",
        "provider": "example",
        "provider_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
        "provider_type": "example",
        "serving_backend": "example"
      },
      "model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "organization_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "output_tokens": 1,
      "parent_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "prompt_tokens": 1,
      "provider_model_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "provider_request_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "provider_type": "example",
      "role": "user",
      "sandbox_instance_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "schema_version": 1,
      "session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "thread_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "tool_name": "example",
      "tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "turn_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
    }
  ],
  "next_page_token": "example"
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

A Recursion API key, created in the console under API keys.

Path Parameters

session_id

string<uuid>

required

Session id (UUID) whose root timeline is read.

Query Parameters

after_event_id

string

Exclusive continuation cursor: a lowercase canonical UUID event id, normally the previous page's next_page_token. Malformed values return 400.

limit

integer

default:100

Maximum event count requested. The response may contain fewer events when the aggregate serialized-byte budget is reached.

hydrate

enum<string>

Opt-in compatibility mode. images rehydrates private image refs under strict response caps; omitted by default.

Available options:

images

image_urls

enum<string>

Set to signed to add a short-lived url (and url_expires_at) to stored image blocks within the per-read signing budget. Omitted when signing is unavailable or the budget is exhausted; the authenticated getSessionImage endpoint always works.

Available options:

signed

payloads

enum<string>

External event payloads hydrate by default. Set refs to return bounded stubs and private reference metadata only.

Available options:

refs

Response

Response body of GET /v1/sessions/{session_id}/events: one page of the merged chronological timeline for the whole session tree the path session belongs to, not just that session's own events. The page is bounded twice, by the limit parameter and by an aggregate serialized-byte budget, and the byte budget wins; a single event too large for the budget is returned alone with its content marked oversized and must be fetched in full from the per-event content endpoint.

events

object[] | null

required

One chronological page of the root timeline, oldest first. Null rather than an empty array when no event follows the requested watermark, which is the normal answer when a caller has already read to the end.

Show child attributes

next_page_token

string

required

Watermark to continue from: pass it back as the after_event_id query parameter to fetch the next page. Its value is the event_id of the last event in this page. Always present, and an empty string means this page reached the end of the timeline as of this read. Because the page can be cut short by a byte budget before the requested limit is reached, a short events array with a non-empty token means more remain, not that the timeline ended.

API reference

Endpoints

Get root timeline events

Authorizations

Path Parameters

Query Parameters

Response