List Sessions

Retrieve paginated list of sessions with filtering and sorting options. Supports filtering by session type (agent, team, workflow), component, user, and name. Sessions represent conversation histories and execution contexts.

GET /sessions

List Sessions

cURL

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

import requests

url = "https://api.example.com/sessions"

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

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

print(response.text)

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

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

	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))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/sessions")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/sessions")

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

200

{
  "session_example": {
    "summary": "Example session response",
    "value": {
      "data": [
        {
          "session_id": "6f6cfbfd-9643-479a-ae47-b8f32eb4d710",
          "session_name": "What tools do you have?",
          "session_state": {},
          "created_at": "2025-09-05T16:02:09Z",
          "updated_at": "2025-09-05T16:02:09Z"
        }
      ]
    }
  }
}

{
  "detail": "Bad request",
  "error_code": "BAD_REQUEST"
}

{
  "detail": "Unauthenticated access",
  "error_code": "UNAUTHENTICATED"
}

{
  "detail": "Not found",
  "error_code": "NOT_FOUND"
}

{
  "detail": "Validation error",
  "error_code": "VALIDATION_ERROR"
}

{
  "detail": "Internal server error",
  "error_code": "INTERNAL_SERVER_ERROR"
}

Authorizations

Authorization · string · header · required

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

Query Parameters

type · enum<string> · default: agent

Type of sessions to retrieve (agent, team, or workflow)

Available options: agent, team, workflow

component_id · string | null

Filter sessions by component ID (agent/team/workflow ID)

user_id · string | null

Filter sessions by user ID

session_name · string | null

Filter sessions by name (partial match)

limit · integer | null · default: 20

Number of sessions to return per page

Required range: x >= 1

page · integer | null · default: 1

Page number for pagination

Required range: x >= 0

sort_by · string | null · default: created_at

Field to sort sessions by

sort_order · enum<string> | null · default: desc

Sort order (asc or desc)

Available options: asc, desc

db_id · string | null

Database ID to query sessions from

table · string | null

The database table to use

Response

200

application/json

Sessions retrieved successfully

data · SessionSchema · object[] · required

List of items for the current page

Show child attributes

meta · PaginationInfo · object · required

Pagination metadata

Show child attributes