Get Session

Retrieve details for a specific session

GET /api/v1/sessions/{session_id}

Get Session

cURL

curl --request GET \
  --url https://api.example.com/api/v1/sessions/{session_id} \
  --header 'X-API-Key: <x-api-key>'

200

{
  "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

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"
  }
}

Related Endpoints

• Create Session - Create a new session
• List Sessions - List all sessions
• Add Message - Add messages to session
• Commit Session - Archive and extract memories
• Delete Session - Delete a session