​

Scenario Event Schema

The Simulations visualizer is powered by a single endpoint that receives events from your test runs. All events are sent via a POST request to the following endpoint:

/api/scenario-events

The request body should be a JSON object representing one of the event types described below. These events allow LangWatch to reconstruct the entire history of your simulation sets, batches, and individual scenario runs.

For a detailed look at the request and response models, see the Create Event endpoint reference.

​

Common Properties

All scenario events share a common set of properties to identify and organize them:

• type: The specific type of the event.
• timestamp: A Unix timestamp (in milliseconds) of when the event occurred.
• batchRunId: An ID that groups all scenarios run within the same test execution or process.
• scenarioId: A stable identifier for a specific scenario (e.g., “test_vegetarian_recipe”).
• scenarioRunId: A unique ID for a single execution of a scenario.
• scenarioSetId: The top-level grouping for a collection of scenarios, which defaults to "default".

​

Event Types

There are three main types of events that you can send.

​

1. SCENARIO_RUN_STARTED

This event marks the beginning of a new scenario run.

• metadata:
  • name: The display name of the scenario.
  • description: A longer description of what the scenario tests.

​

2. SCENARIO_MESSAGE_SNAPSHOT

This event captures the state of the conversation at a specific point in time. It includes an array of messages exchanged between the user, agent, and tools.

• messages: An array of message objects. The schema for these messages (user, assistant, tool, etc.) is detailed in the OpenAPI specification.

​

3. SCENARIO_RUN_FINISHED

This event marks the end of a scenario run and includes the final results.

• status: The final status of the run (SUCCESS, FAILED, ERROR, etc.).
• results: An object containing the final verdict from a Judge Agent, including:
  • verdict: The final outcome (success, failure).
  • reasoning: The explanation for the verdict.
  • metCriteria: A list of criteria that were satisfied.
  • unmetCriteria: A list of criteria that were not met.