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 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.
Send the first message with a session value
from forgebench import Forgebench client = Forgebench(api_key="sk_...", base_url="https://api.forgebench.ai") client.chat.completions.create( model="mock-gpt", messages=[{"role": "user", "content": "How do I reset my password?"}], extra_body={"metadata": {"dimensions": {"session": "conv_8f21"}}}, )import { Forgebench, type ChatCompletionRequest } from "@seedlinglabs/forgebench-sdk"; const forgebench = new Forgebench({ apiKey: "sk_...", baseUrl: "https://api.forgebench.ai" }); await forgebench.chat.create({ model: "mock-gpt", messages: [{ role: "user", content: "How do I reset my password?" }], metadata: { dimensions: { session: "conv_8f21" } }, } as ChatCompletionRequest & Record<string, unknown>);import ai.forgebench.ChatCompletionRequest; import ai.forgebench.ChatMessage; import ai.forgebench.Forgebench; import java.util.Map; Forgebench client = Forgebench.builder().apiKey("sk_...").baseUrl("https://api.forgebench.ai").build(); client.chat().completions().create(ChatCompletionRequest.builder() .model("mock-gpt") .addMessage(ChatMessage.user("How do I reset my password?")) .extraBody(Map.of("metadata", Map.of("dimensions", Map.of("session", "conv_8f21")))) .build());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.
Send the next message with the SAME session value
Reusing the same
client/forgebenchfrom the previous step:client.chat.completions.create( model="mock-gpt", messages=[{"role": "user", "content": "That did not work, now what?"}], extra_body={"metadata": {"dimensions": {"session": "conv_8f21"}}}, )await forgebench.chat.create({ model: "mock-gpt", messages: [{ role: "user", content: "That did not work, now what?" }], metadata: { dimensions: { session: "conv_8f21" } }, } as ChatCompletionRequest & Record<string, unknown>);client.chat().completions().create(ChatCompletionRequest.builder() .model("mock-gpt") .addMessage(ChatMessage.user("That did not work, now what?")) .extraBody(Map.of("metadata", Map.of("dimensions", Map.of("session", "conv_8f21")))) .build());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
sessionvalue 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.