Get Session By Id

Storage and ownership

Start the example API server and create a run or precreate a session. Keep the returned session_id. Use db_id when multiple registered databases exist; selecting table requires db_id and a configured adapter. It does not create a table on demand.

The session-type query parameter is type=agent, type=team or type=workflow. JWT user isolation is opt-in; non-admin service-account PAT callers always self-scope. A supplied user_id is a filter for unscoped callers, not permission to access another owner's records. Configured authorization also requires the relevant session read, write or delete scope.

Read a session

Using a session returned by the linked example server:

SESSION_ID="returned-session-id"
curl --fail-with-body --get "http://127.0.0.1:7777/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  --data-urlencode 'type=agent'

Agent and Team details include chat_history. Workflow details expose session/workflow data and state, without that chat-history field. Use Get Session Runs for stored run records. Model IDs and system messages in generated historical examples are sample data, not current model or prompt defaults.

GET/sessions/{session_id}

Retrieve detailed information about a specific session including metadata, configuration, and run history. Response schema varies based on session type (agent, team, or workflow).

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

session_id*Session Id

Session ID to retrieve

Query Parameters

type?|

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

user_id?|

User ID to query session from

db_id?|

Database ID to query session from

table?|

Table to query session from

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request GET 'https://example.com/sessions/string'
{  "user_id": "123",  "agent_session_id": "6f6cfbfd-9643-479a-ae47-b8f32eb4d710",  "session_id": "6f6cfbfd-9643-479a-ae47-b8f32eb4d710",  "session_name": "What tools do you have?",  "session_summary": {    "summary": "The user and assistant engaged in a conversation about the tools the agent has available.",    "updated_at": "2025-09-05T18:02:12.269392"  },  "session_state": {},  "agent_id": "basic-agent",  "total_tokens": 160,  "agent_data": {    "name": "Basic Agent",    "agent_id": "basic-agent",    "model": {      "provider": "OpenAI",      "name": "OpenAIChat",      "id": "gpt-4o"    }  },  "metrics": {    "input_tokens": 134,    "output_tokens": 26,    "total_tokens": 160,    "audio_input_tokens": 0,    "audio_output_tokens": 0,    "audio_total_tokens": 0,    "cache_read_tokens": 0,    "cache_write_tokens": 0,    "reasoning_tokens": 0  },  "chat_history": [    {      "content": "<additional_information>\n- Use markdown to format your answers.\n- The current time is 2025-09-05 18:02:09.171627.\n</additional_information>\n\nYou have access to memories from previous interactions with the user that you can use:\n\n<memories_from_previous_interactions>\n- User really likes Digimon and Japan.\n- User really likes Japan.\n- User likes coffee.\n</memories_from_previous_interactions>\n\nNote: this information is from previous interactions and may be updated in this conversation. You should always prefer information from this conversation over the past memories.",      "from_history": false,      "stop_after_tool_call": false,      "role": "system",      "created_at": 1757088129    },    {      "content": "What tools do you have?",      "from_history": false,      "stop_after_tool_call": false,      "role": "user",      "created_at": 1757088129    },    {      "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": 134,        "output_tokens": 26,        "total_tokens": 160      },      "created_at": 1757088129    }  ],  "created_at": "2025-09-05T16:02:09Z",  "updated_at": "2025-09-05T16:02:09Z"}