Get Session Runs

curl --request GET \
  --url https://api.example.com/sessions/{session_id}/runs \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.example.com/sessions/{session_id}/runs', 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.example.com/sessions/{session_id}/runs",
  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.example.com/sessions/{session_id}/runs"

	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.example.com/sessions/{session_id}/runs")

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

{
  "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
  "parent_run_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0",
  "agent_id": "basic-agent",
  "user_id": "",
  "run_input": "Which tools do you have access to?",
  "content": "I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!",
  "run_response_format": "text",
  "reasoning_content": "",
  "metrics": {
    "input_tokens": 82,
    "output_tokens": 56,
    "total_tokens": 138,
    "time_to_first_token": 0.047505500027909875,
    "duration": 4.840060166025069
  },
  "messages": [
    {
      "content": "<additional_information>\n- Use markdown to format your answers.\n- The current time is 2025-09-08 17:52:10.101003.\n</additional_information>\n\nYou have the capability to retain memories from previous interactions with the user, but have not had any interactions with the user yet.",
      "from_history": false,
      "stop_after_tool_call": false,
      "role": "system",
      "created_at": 1757346730
    },
    {
      "content": "Which tools do you have access to?",
      "from_history": false,
      "stop_after_tool_call": false,
      "role": "user",
      "created_at": 1757346730
    },
    {
      "content": "I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!",
      "from_history": false,
      "stop_after_tool_call": false,
      "role": "assistant",
      "metrics": {
        "input_tokens": 82,
        "output_tokens": 56,
        "total_tokens": 138
      },
      "created_at": 1757346730
    }
  ],
  "events": [
    {
      "created_at": 1757346730,
      "event": "RunStarted",
      "agent_id": "basic-agent",
      "agent_name": "Basic Agent",
      "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
      "session_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0",
      "model": "gpt-4o",
      "model_provider": "OpenAI"
    },
    {
      "created_at": 1757346733,
      "event": "MemoryUpdateStarted",
      "agent_id": "basic-agent",
      "agent_name": "Basic Agent",
      "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
      "session_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0"
    },
    {
      "created_at": 1757346734,
      "event": "MemoryUpdateCompleted",
      "agent_id": "basic-agent",
      "agent_name": "Basic Agent",
      "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
      "session_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0"
    },
    {
      "created_at": 1757346734,
      "event": "RunCompleted",
      "agent_id": "basic-agent",
      "agent_name": "Basic Agent",
      "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
      "session_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0",
      "content": "I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!",
      "content_type": "str",
      "metrics": {
        "input_tokens": 82,
        "output_tokens": 56,
        "total_tokens": 138,
        "time_to_first_token": 0.047505500027909875,
        "duration": 4.840060166025069
      }
    }
  ],
  "created_at": "2025-09-08T15:52:10Z"
}

{
  "detail": "Bad request"
}

{
  "detail": "Unauthenticated access"
}

{
  "detail": "Not found"
}

{
  "detail": [
    {
      "loc": [
        "body",
        "endpoint"
      ],
      "msg": "Value error, Endpoint must be a path, not a full URL",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Internal server error"
}

GET

sessions

{session_id}

runs

Get Session Runs

curl --request GET \
  --url https://api.example.com/sessions/{session_id}/runs \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.example.com/sessions/{session_id}/runs', 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.example.com/sessions/{session_id}/runs",
  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.example.com/sessions/{session_id}/runs"

	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.example.com/sessions/{session_id}/runs")

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

{
  "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
  "parent_run_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0",
  "agent_id": "basic-agent",
  "user_id": "",
  "run_input": "Which tools do you have access to?",
  "content": "I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!",
  "run_response_format": "text",
  "reasoning_content": "",
  "metrics": {
    "input_tokens": 82,
    "output_tokens": 56,
    "total_tokens": 138,
    "time_to_first_token": 0.047505500027909875,
    "duration": 4.840060166025069
  },
  "messages": [
    {
      "content": "<additional_information>\n- Use markdown to format your answers.\n- The current time is 2025-09-08 17:52:10.101003.\n</additional_information>\n\nYou have the capability to retain memories from previous interactions with the user, but have not had any interactions with the user yet.",
      "from_history": false,
      "stop_after_tool_call": false,
      "role": "system",
      "created_at": 1757346730
    },
    {
      "content": "Which tools do you have access to?",
      "from_history": false,
      "stop_after_tool_call": false,
      "role": "user",
      "created_at": 1757346730
    },
    {
      "content": "I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!",
      "from_history": false,
      "stop_after_tool_call": false,
      "role": "assistant",
      "metrics": {
        "input_tokens": 82,
        "output_tokens": 56,
        "total_tokens": 138
      },
      "created_at": 1757346730
    }
  ],
  "events": [
    {
      "created_at": 1757346730,
      "event": "RunStarted",
      "agent_id": "basic-agent",
      "agent_name": "Basic Agent",
      "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
      "session_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0",
      "model": "gpt-4o",
      "model_provider": "OpenAI"
    },
    {
      "created_at": 1757346733,
      "event": "MemoryUpdateStarted",
      "agent_id": "basic-agent",
      "agent_name": "Basic Agent",
      "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
      "session_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0"
    },
    {
      "created_at": 1757346734,
      "event": "MemoryUpdateCompleted",
      "agent_id": "basic-agent",
      "agent_name": "Basic Agent",
      "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
      "session_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0"
    },
    {
      "created_at": 1757346734,
      "event": "RunCompleted",
      "agent_id": "basic-agent",
      "agent_name": "Basic Agent",
      "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
      "session_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0",
      "content": "I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!",
      "content_type": "str",
      "metrics": {
        "input_tokens": 82,
        "output_tokens": 56,
        "total_tokens": 138,
        "time_to_first_token": 0.047505500027909875,
        "duration": 4.840060166025069
      }
    }
  ],
  "created_at": "2025-09-08T15:52:10Z"
}

{
  "detail": "Bad request"
}

{
  "detail": "Unauthenticated access"
}

{
  "detail": "Not found"
}

{
  "detail": [
    {
      "loc": [
        "body",
        "endpoint"
      ],
      "msg": "Value error, Endpoint must be a path, not a full URL",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Internal server error"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

session_id

string

required

Session ID to get runs from

Query Parameters

type

enum<string> | null

Session type (agent, team, or workflow). If not provided, auto-detected from session data.

Available options:

agent,

team,

workflow

user_id

string | null

User ID to query runs from

created_after

integer | null

Filter runs created after this Unix timestamp (epoch time in seconds)

created_before

integer | null

Filter runs created before this Unix timestamp (epoch time in seconds)

db_id

string | null

Database ID to query runs from

table

string | null

Table to query runs from

Response

Session runs retrieved successfully

RunSchema
TeamRunSchema
WorkflowRunSchema

run_id

string

required

Unique identifier for the run

parent_run_id

string | null

Parent run ID if this is a nested run

agent_id

string | null

Agent ID that executed this run

user_id

string | null

User ID associated with the run

status

string | null

Run status (PENDING, RUNNING, COMPLETED, ERROR, etc.)

run_input

string | null

Input provided to the run

content

Output content from the run

run_response_format

string | null

Format of the response (text/json)

reasoning_content

string | null

Reasoning content if reasoning was enabled

reasoning_steps

Reasoning Steps · object[] | null

List of reasoning steps

metrics

Metrics · object | null

Performance and usage metrics

messages

Messages · object[] | null

Message history for the run

tools

Tools · object[] | null

Tools used in the run

events

Events · object[] | null

Events generated during the run

created_at

string<date-time> | null

Run creation timestamp

references

References · object[] | null

References cited in the run

citations

Citations · object | null

Citations from the model (e.g., from Gemini grounding/search)

reasoning_messages

Reasoning Messages · object[] | null

Reasoning process messages

session_state

Session State · object | null

Session state at the end of the run

images

Images · object[] | null

Images included in the run

videos

Videos · object[] | null

Videos included in the run

audio

Audio · object[] | null

Audio files included in the run

files

Files · object[] | null

Files included in the run

response_audio

Response Audio · object | null

Audio response if generated

input_media

Input Media · object | null

Input media attachments

followups

string[] | null

Followup suggestions generated after the run

forked_from_run_id

string | null

If this run was forked from another run, the source run's ID

forked_from_message_index

integer | null

If this run was forked, the message index at which the source was truncated

forked_from_session_id

string | null

If this run was created via session branch, the source session's ID

regenerated_from

string | null

If this run was produced via regenerate=true, the source run's ID

last_checkpoint_at_message_index

integer | null

Message index of the most recent mid-run checkpoint (checkpoint='tool-batch' runs)

Agno SDK Reference

AgentOS API Reference

Agno CLI

Agno Infra CLI

Get Session Runs

Authorizations

Path Parameters

Query Parameters

Response