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:
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.
Last modified on May 19, 2026
