Concepts

Sessions

Orqen automatically groups your agent's requests into sessions so you can see the full arc of each conversation — tools called, tokens saved, and latency per turn — without any code changes.

How sessions work

Every request you make through Orqen is automatically assigned to a session. Two requests from the same API key within 30 minutes of each other are grouped into the same session. A gap longer than 30 minutes starts a new session.

This matches how real agent conversations work: a user starts a task, the agent makes several requests back and forth, the conversation ends. If the user comes back an hour later, that's a new session.

What you can see in each session

The Sessions dashboard shows every turn in the conversation, with per-turn detail:

• ✓Which model was used and whether it was routed by Orqen
• ✓How many tools were sent vs how many Orqen forwarded
• ✓Compression savings from deduplication and context trimming
• ✓Full latency breakdown — dedup, compression, tool routing, and upstream LLM separately
• ✓Which tools the LLM actually called after tool routing
• ✓Orqen's overhead as a percentage of total request time

Grouping conversations manually

The automatic 30-minute window works for most agents. If you want to group a specific conversation under your own ID — for example, to tie an Orqen session to a user session in your own database — pass X-Orqen-Session-Id in your request headers:

from openai import OpenAI

client = OpenAI(
    api_key="sk-orq-YOUR_KEY",
    base_url="https://api.orqen.app/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    extra_headers={"x-orqen-session-id": "user-abc123-chat-7"},
)

All requests with the same X-Orqen-Session-Id value are grouped together regardless of timing. Manual IDs also reset the 30-minute auto-session window, so a request with an explicit ID continues whatever session was active.

How sessions improve routing

Sessions aren't just for observability — they actively improve Orqen's routing accuracy:

• ↑Session-consistent routing: Tools the LLM has already called in this session get a score boost on subsequent turns. If the LLM called get_weather in turn 2, it's more likely to be included in turn 3's forwarded set.
• ↑Cache-stable routing: When your request uses Anthropic's prompt caching (cache_control), Orqen prefers to select the same tool subset as the previous turn so the provider's prefix cache stays valid across turns.

Session search

In the Sessions dashboard you can search by session ID, model name, or tool name. This lets you quickly find all conversations that involved a specific tool (useful for debugging routing misses) or all sessions that used a particular model.