Sessions

A session groups several related calls together as a single conversation, rather than a set of unrelated rows in the trace list. This is the view to use when a report describes something going wrong over several messages: "it got confused after a few replies," rather than in a single call.

Creating a session

A session is created simply by reusing the same value in the session key of a call's metadata across every call that belongs to it. There is no separate step to create a session beforehand; sending the same value twice is what groups the two calls together.

1. Send the first message with a session value

   curlPythonTypeScript

   curl -X POST https://api.forgebench.ai/v1/chat/completions \
   -H "Authorization: Bearer sk_..." \
   -H "Content-Type: application/json" \
   -d '{
     "model": "mock-gpt",
     "messages": [{"role": "user", "content": "How do I reset my password?"}],
     "metadata": { "dimensions": { "session": "conv_8f21" } }
   }'

   On its own, this call appears in the trace list as usual.

2. Send the next message with the SAME session value

   Reusing the same client/forgebench from the previous step:

   curlPythonTypeScript

   curl -X POST https://api.forgebench.ai/v1/chat/completions \
   -H "Authorization: Bearer sk_..." \
   -H "Content-Type: application/json" \
   -d '{
     "model": "mock-gpt",
     "messages": [{"role": "user", "content": "That did not work, now what?"}],
     "metadata": { "dimensions": { "session": "conv_8f21" } }
   }'

   Because it carries the same session value as the first, the two are now grouped together as one conversation.

A practical source for this value is whatever your own application already uses to identify a conversation or a ticket, so the two line up without inventing a second identifier.

Reading the sessions view

The session list shows one row per session, with the number of calls it contains and its total cost. Opening a session shows those calls in order, alongside the same totals for the conversation as a whole. This is the figure to use when the question is "what did this conversation cost", rather than adding up individual calls by hand.

Next