Skip to main content
GET
/
api
/
v1
/
sessions
/
{session_id}
Get Session
curl --request GET \
  --url https://api.example.com/api/v1/sessions/{session_id} \
  --header 'X-API-Key: <x-api-key>'
{
  "status": "<string>",
  "result": {
    "session_id": "<string>",
    "user": {
      "user_id": "<string>",
      "agent_id": "<string>"
    },
    "message_count": 123
  },
  "time": 123
}
Get metadata and statistics for an existing conversation session.

​
Request

​
Path Parameters

​
session_id
string
required
The session ID to retrieve

​
Headers

​
X-API-Key
string
required
Your OpenViking API key for authentication

​
Response

​
status
string
Response status (ok or error)
​
result
object
Session details
​
session_id
string
The session identifier
​
user
object
User information associated with the session
​
user_id
string
User identifier
​
agent_id
string
Agent identifier
​
message_count
number
Number of messages currently in the session
​
time
number
Request processing time in seconds

​
Examples

curl -X GET http://localhost:1933/api/v1/sessions/a1b2c3d4 \
  -H "X-API-Key: your-api-key"

​
Response Example

{
  "status": "ok",
  "result": {
    "session_id": "a1b2c3d4",
    "user": {
      "user_id": "alice",
      "agent_id": "default"
    },
    "message_count": 8
  },
  "time": 0.1
}

​
Session Properties (Python SDK)

When using the Python SDK, the Session object provides rich properties:

​
Basic Properties

session = client.session(session_id="a1b2c3d4")
session.load()

# Session identification
print(session.session_id)  # "a1b2c3d4"
print(session.uri)         # "viking://session/alice/a1b2c3d4/"
print(session.user)        # UserIdentifier object

# Messages
print(len(session.messages))  # Current message count
for msg in session.messages:
    print(f"{msg.role}: {msg.content}")

​
Statistics

stats = session.stats

print(f"Total turns: {stats.total_turns}")
print(f"Total tokens: {stats.total_tokens}")
print(f"Compression count: {stats.compression_count}")
print(f"Contexts used: {stats.contexts_used}")
print(f"Skills used: {stats.skills_used}")
print(f"Memories extracted: {stats.memories_extracted}")

​
Compression Info

compression = session.compression

print(f"Summary: {compression.summary}")
print(f"Original count: {compression.original_count}")
print(f"Compressed count: {compression.compressed_count}")
print(f"Compression index: {compression.compression_index}")

​
Usage Records

# Track what was actually used
for usage in session.usage_records:
    print(f"Type: {usage.type}")  # "context" or "skill"
    print(f"URI: {usage.uri}")
    print(f"Success: {usage.success}")
    print(f"Timestamp: {usage.timestamp}")

​
Use Cases

​
Resume Previous Conversation

import openviking as ov

client = ov.OpenViking(path="./my_data")
client.initialize()

# Load existing session
session = client.session(session_id="a1b2c3d4")
session.load()

if session.messages:
    print("Previous conversation:")
    for msg in session.messages[-5:]:  # Last 5 messages
        print(f"{msg.role}: {msg.content}")
    
    # Continue conversation
    session.add_message("user", [TextPart(text="What did we discuss earlier?")])
else:
    print("Session is empty")

​
Check Session Health

session = client.session(session_id="a1b2c3d4")
session.load()

# Check if session needs compression
if session.stats.total_tokens > 8000:
    print("Session is getting long, consider committing")
    result = session.commit()
    print(f"Archived and extracted {result['memories_extracted']} memories")

​
Analyze Session Activity

session = client.session(session_id="a1b2c3d4")
session.load()

print(f"Session Activity Report")
print(f"="*50)
print(f"Total turns: {session.stats.total_turns}")
print(f"Messages: {len(session.messages)}")
print(f"Archives: {session.stats.compression_count}")
print(f"\nContext Usage:")
print(f"  Contexts referenced: {session.stats.contexts_used}")
print(f"  Skills called: {session.stats.skills_used}")
print(f"\nMemory Extraction:")
print(f"  Memories extracted: {session.stats.memories_extracted}")

​
Error Responses

​
Session Not Found

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Session a1b2c3d4 not found"
  }
}