Sessions & Metadata

Sessions

A session groups related LLM calls together, such as a user conversation, agent run, or batch job. Assign a session ID and all traces with that ID appear as a timeline in the dashboard.

Setting a session ID

At observe-time

Pass sessionId in observe options. All calls through this client use this session.

TypeScript
Python

const client = observe(
  new OpenAI({ apiKey: "sk-..." }),
  Provider.OpenAI,
  { sessionId: "conv-abc-123" }
);

client = observe(
  OpenAI(api_key="sk-..."),
  Provider.OPENAI,
  { "session_id": "conv-abc-123" }
)

Per-call override

Pass pulseSessionId in the request body to override the observe-time session for one call.

TypeScript
Python

await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
  pulseSessionId: "different-session-456",
});

client.chat.completions.create(
  model="gpt-4o",
  messages=[{"role": "user", "content": "Hello"}],
  pulse_session_id="different-session-456",
)

Per-call values take precedence. pulseSessionId is stripped before the request reaches the provider.

Metadata

Attach arbitrary key-value data to traces for filtering by user, feature, environment, or any custom dimension.

const client = observe(
  new OpenAI({ apiKey: "sk-..." }),
  Provider.OpenAI,
  {
    metadata: {
      userId: "user-123",
      environment: "production",
    },
  }
);

client = observe(
  OpenAI(api_key="sk-..."),
  Provider.OPENAI,
  {
    "metadata": {
      "user_id": "user-123",
      "environment": "production",
    }
  }
)

Per-call extension

Pass pulseMetadata in request body. It merges with observe-time metadata and per-call values win on conflicts.

TypeScript
Python

await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Summarize this" }],
  pulseMetadata: {
    feature: "summarizer",
    version: "2.1",
  },
});

client.chat.completions.create(
  model="gpt-4o",
  messages=[{"role": "user", "content": "Summarize this"}],
  pulse_metadata={
    "feature": "summarizer",
    "version": "2.1",
  },
)

ObserveOptions

The third argument to observe():

Field	Type	Description
`sessionId`	`string`	Default session ID for all calls through the client.
`metadata`	`Record<string, unknown>`	Metadata merged into every trace from this client.

Per-call params

These request fields are stripped before sending to the provider:

Field	Type	Description
`pulseSessionId`	`string`	Override session ID for this call only.
`pulseMetadata`	`Record<string, unknown>`	Merge additional metadata for this call.

Viewing sessions

In the dashboard, navigate to Sessions to see traces grouped by session ID and ordered by timestamp.

Via API:

GET /v1/sessions/:id

Returns all traces for the session. See REST API.