Skip to main content

Using sessions and traces

What you'll build: three tour-planning prompts called one after another as part of a single trip-planning "session," so you can see them grouped in the frontend, drill down into one call's trace, leave feedback on it, and jump back to the exact prompt that produced it.

Every gateway call is already recorded as a trace — a record of one request, its spans (a span is one unit of work, like the LLM call itself), tokens, and cost. A session is a lightweight way to say "these several traces belong to the same user flow." You tag each call with the same session id, and the frontend rolls them up into one view — handy when one user action (like planning a trip) triggers several prompt calls in a row.

Full runnable script

A standalone script exercising this whole flow lives at scripts/guides/using-sessions-and-traces on GitHub.

1. Register the prompts​

This guide uses a tour-planner theme: three separate prompts that together plan a trip. Prompts → New prompt, create tour-itinerary-planner, tour-budget-estimator, and tour-packing-list-generator, each with its own system message and variables (e.g. {{ destination }}, {{ days }}). See Version a prompt if you haven't created one before.

Prompts list showing tour-itinerary-planner, tour-budget-estimator, and tour-packing-list-generator

2. Call all three under one session​

Send each prompt through the gateway with the same session id — an x-session-id header on a raw gateway request, or sessionId in the SDK's trace: option. Each call still gets its own trace, but they all share the session id — that's the only thing that ties them together as one flow.

curl -X POST "$ACRUXCORE_BASE_URL/gateway/chat/completions" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-session-id: tokyo-trip-plan-01" \
  -d '{"prompt":{"name":"tour-itinerary-planner","alias":"production","variables":{"days":"3","destination":"Tokyo"}}}'

Repeat for the other two prompts with the same session id (the SDK examples above already loop through all three). Open Observability → Sessions and the session shows up with all three calls rolled into it — trace count, total tokens, and the time span they happened in.

Sessions list with one row: tokyo-trip-plan-01, 3 traces, 461 tokens

note

A session is never created directly — it's just a sessionId string shared by one or more traces, and it doesn't start on its own. The first call that uses a new session id "creates" it; every later call you want in that conversation must carry the same id — an x-session-id header on a gateway request, or sessionId in the SDK's trace: option. A call with no session id lands as a standalone trace.

3. Open the session and drill into a trace​

Click the session row to see every trace that shares its id — one per prompt call, newest first.

Session detail page listing the three tour-planner traces with their token counts and durations

Click any trace's timestamp to open it. Expand the LLM span to see the resolved model, token usage, latency — and a link back to the prompt version that produced this exact call.

Trace detail page with the LLM span expanded, showing model, provider, tokens, and latency

4. Leave feedback​

Scroll to the Feedback panel at the bottom of the trace (or use the thumbs on an individual span, if you want feedback scoped to just that unit of work). Pick thumbs up or down, optionally add a short label and comment, then submit.

Feedback form filled in with a thumbs-up rating, a label, and a comment, before submitting

Once saved, your feedback appears in the list above the form, and the expanded span shows a "View traces for this prompt version →" link — this is the path back to the prompt.

Saved feedback entry above the span panel's "View traces for this prompt version" link

5. Navigate back to the prompt​

Click that link. It takes you to the Traces list pre-filtered to only calls made against that one prompt version — confirming exactly which version this feedback belongs to.

Traces list filtered to a single prompt version, showing only the matching call

From there, open Prompts and pick the same prompt by name (here, tour-packing-list-generator) to go straight to its versions, aliases, and editor — closing the loop from a piece of feedback all the way back to the prompt that earned it.

Doing this over the API​

Sessions and feedback are both first-class API resources, so you can build the same flow — call, group, read back, and record feedback — entirely from code.

# List sessions
curl "$ACRUXCORE_BASE_URL/sessions" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"
{
  "data": [
    {
      "sessionId": "tokyo-trip-plan-01",
      "traceCount": 3,
      "totalCostUsd": null,
      "totalTokens": 461,
      "firstAt": "2026-07-12T18:36:44.950Z",
      "lastAt": "2026-07-12T18:36:59.152Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}
# Get one session and its traces
curl "$ACRUXCORE_BASE_URL/sessions/tokyo-trip-plan-01" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"
{
  "session": {
    "sessionId": "tokyo-trip-plan-01",
    "traceCount": 3,
    "totalCostUsd": null,
    "totalTokens": 461,
    "firstAt": "2026-07-12T18:36:44.950Z",
    "lastAt": "2026-07-12T18:36:59.152Z"
  },
  "traces": [
    {
      "id": "bede0c1b-3d8e-40ef-950d-f5198f453ee7",
      "name": "tour-packing-list-generator call",
      "sessionId": "tokyo-trip-plan-01",
      "status": "ok",
      "spanCount": 1,
      "totalTokens": 177
    }
  ]
}
# Leave feedback on a trace (omit spanId for whole-trace feedback)
curl -X POST "$ACRUXCORE_BASE_URL/traces/bede0c1b-3d8e-40ef-950d-f5198f453ee7/feedback" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating":1,"label":"helpful-packing-list","comment":"Covers layering and rain gear well for Tokyo autumn."}'
{
  "id": "be698c98-11f5-47a4-bfb7-df692da87c82",
  "traceId": "bede0c1b-3d8e-40ef-950d-f5198f453ee7",
  "spanId": null,
  "rating": 1,
  "label": "helpful-packing-list",
  "comment": "Covers layering and rain gear well for Tokyo autumn.",
  "source": "user",
  "createdAt": "2026-07-12T18:40:23.697Z"
}

source defaults to "user" when omitted from the request, as it is above — it also accepts "developer", "end_user", or "api" if you want to record where feedback actually came from.

Feedback also aggregates: an average rating grouped by model or prompt version, and a team-wide raw feed across every trace.

# Average rating + counts, grouped by model
curl "$ACRUXCORE_BASE_URL/traces/feedback/summary?group_by=model" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"
{
  "groupBy": "model",
  "buckets": [{ "key": "gpt-4o-mini", "count": 2, "avgRating": 0, "downCount": 1 }]
}
# Team-wide feedback feed, newest first
curl "$ACRUXCORE_BASE_URL/traces/feedback?limit=5" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"
{
  "data": [
    { "id": "68812680-562a-4ef5-8c72-a076da209afe", "traceId": "d65be577-5701-4ea5-97b0-995815d89226", "spanId": null, "rating": -1, "label": "too-verbose", "comment": null, "source": "developer", "createdBy": "a41d471d-7752-4795-bf59-79ef44ac67f3", "createdAt": "2026-08-04T19:26:21.478Z", "updatedAt": "2026-08-04T19:26:21.478Z" },
    { "id": "5dfcf43a-8ad5-480d-a244-12592542acaa", "traceId": "d65be577-5701-4ea5-97b0-995815d89226", "spanId": null, "rating": 1, "label": "helpful-answer", "comment": "Clear and accurate.", "source": "user", "createdBy": "a41d471d-7752-4795-bf59-79ef44ac67f3", "createdAt": "2026-08-04T19:26:21.459Z", "updatedAt": "2026-08-04T19:26:21.459Z" }
  ],
  "total": 2,
  "page": 1,
  "limit": 5
}

avgRating counts non-null ratings only (downCount is the number rated below zero); a group with no feedback yet is simply absent from buckets.

What's next​