Copilot event tracking

You can track actions performed by your users with AI copilots, along with properties describing the event. This allows you to measure and analyze the quality of your copilot experience and identify opportunities for improvement.

How It Works

We can leverage our event tracking capabilities for copilots:

• Every user prompt sent is tracked as an event.

• Every copilot response is tracked as an event.

Optional events (like conversions or satisfaction) can be added to analyze success and user sentiment.

By adding properties to these events, you can provide additional context.

Most common integration mistake

The #1 mistake we see: calling screeb_copilot_user_prompt / screeb_copilot_response only once instead of firing them again on every turn of the conversation, with the same conversation_id, session_id, and agent_id throughout.

If your tracked conversations consistently stop after 1-2 events, this is the first thing to check.

Copilot running server-side?

If your copilot runs server-side (the most common case for an LLM-based assistant), we recommend tracking these events directly via the Screeb server API (see Server-Side Tracking (API) below) instead of the JS tag: it's more reliable, since it avoids the #1 pitfall above (the event not being re-fired on every turn) — the API call lives in the same backend code that already generates the prompt/response.

Events to Track

Mandatory Events

"screeb_copilot_user_prompt"

Triggered when a user sends a message to the copilot.

$screeb("event.copilot", "screeb_copilot_user_prompt", {
  prompt: "How can I export my data?",
  conversation_id: "conv_123",
  session_id: "sess_456",
  agent_id: "agent_789",
  // + any custom properties your product needs
});

Mandatory properties:

• prompt: string
• conversation_id: string
• session_id: string
• agent_id: string

"screeb_copilot_response"

Triggered when the copilot replies to the user.

$screeb("event.copilot", "screeb_copilot_response", {
  response: "You can export your data from the Settings page.",
  conversation_id: "conv_123",
  session_id: "sess_456",
  agent_id: "agent_789",
  // + any custom properties your product needs
});

Mandatory properties:

• response: string
• conversation_id: string
• session_id: string
• agent_id: string

Example: Tracking a Multi-Turn Conversation

These two events are not a one-shot pair fired at the start of a conversation — call them again on every turn, reusing the same conversation_id, session_id, and agent_id for as long as the conversation lasts:

// Created ONCE, when the conversation starts, then reused for every turn.
// Do NOT regenerate these inside the loop below.
const conversationId = `conv_${crypto.randomUUID()}`;
const sessionId = `sess_${crypto.randomUUID()}`;
const agentId = "agent_789";

async function handleUserMessage(prompt) {
  // 1. Track the user prompt for this turn.
  $screeb("event.copilot", "screeb_copilot_user_prompt", {
    prompt,
    conversation_id: conversationId,
    session_id: sessionId,
    agent_id: agentId,
  });

  // 2. Call your copilot to get a response.
  const response = await copilot.ask(prompt);

  // 3. Track the copilot response for this same turn.
  $screeb("event.copilot", "screeb_copilot_response", {
    response,
    conversation_id: conversationId,
    session_id: sessionId,
    agent_id: agentId,
  });

  return response;
}

// Call handleUserMessage() again on every turn of the conversation —
// conversationId/sessionId/agentId stay the same across all calls.
for (const prompt of userPrompts) {
  await handleUserMessage(prompt);
}

Optional Events

"screeb_copilot_conversion"

Triggered when a copilot interaction leads to a conversion (e.g. a purchase, signup, or workflow completion).

$screeb("event.copilot", "screeb_copilot_conversion", {
  agent_id: "agent_789",
  // conversation_id and session_id are optional for conversion events
  // + any custom properties your product needs
});

Mandatory properties:

• agent_id: string

Optional properties:

• conversation_id: string
• session_id: string

"screeb_copilot_satisfaction"

Triggered when a user provides feedback on the copilot interaction.

$screeb("event.copilot", "screeb_copilot_satisfaction", {
  rating_scale: "5",
  rating: "4",
  conversation_id: "conv_123",
  session_id: "sess_456",
  agent_id: "agent_789",
  // + any custom properties
});

Mandatory properties:

• rating_scale: string
• rating: string
• conversation_id: string
• session_id: string
• agent_id: string

Server-Side Tracking (API)

If your copilot runs server-side (e.g. a backend service or data pipeline) and doesn't go through the JS tag, you can send these same events with the Screeb API instead of $screeb("event.copilot", ...).

Use the copilot event type on POST https://api.screeb.app/1.0/event, with the same event_name values described above:

curl -X POST https://api.screeb.app/1.0/event \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my_api_token" \
  -d '[
    {
      "user_alias": "user-123",
      "type": "copilot",
      "event_name": "screeb_copilot_user_prompt",
      "agent_id": "agent_789",
      "conversation_id": "conv_123",
      "copilot_session_id": "sess_456",
      "prompt": "How can I export my data?"
    }
  ]'

Note that some field names differ from the JS tag (e.g. session_id becomes copilot_session_id). See the copilot event type reference for the full field list, authorization, and rate limits.