> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deeprails.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit a Monitor Event
> Use this endpoint to submit a model input and output pair to a monitor for evaluation
Monitor events represent individual LLM usages in your production use case. Whenever you receive a new LLM response, submit an event to this endpoint to have it evaluated.
The request body must include a `model_input` dictionary (containing at least a `system_prompt` field or a `user_prompt` field), a `model_output` string to be evaluated, and a `guardrail_metrics` array specifying which metrics to evaluate against. Optionally, include the `model_used`, selected `run_mode`, and a human-readable `nametag`. Including the `web_search`, `file_search`, and `context_awareness` fields will allow the evaluation model to use those extended AI capabilities.
Run modes determine the models that power evaluations (fastest to most thorough):
- `super_fast` - High-speed lightweight checks
- `fast` - Balanced speed and accuracy (default)
- `precision` - Deep multi-model analysis
- `precision_codex` - Code-optimized deep analysis
- `precision_max` - Exhaustive multi-pass verification
- `precision_max_codex` - Ultimate code-aware verification
Note: `super_fast` does not support Web Search or File Search capabilities. Requests using this mode on monitors with Web Search or File Search enabled will be rejected.
When you create a monitor event, you'll receive an event ID. Use this ID to track the event's progress and retrieve the evaluation results.
## OpenAPI
````yaml /api-reference/openapi.yaml post /monitor/{monitor_id}/events
openapi: 3.0.0
info:
title: DeepRails API
description: >
DeepRails is a powerful developer tool with a comprehensive set of adaptive
& accurate guardrails to protect against LLM hallucinations - deploy our
Monitor and Defend APIs in less than 15 minutes for the best out-of-the-box
guardrails available.
version: v3.0
contact:
name: DeepRails Support
email: support@deeprails.ai
servers:
- url: https://api.deeprails.com
description: Production server
security:
- BearerAuth: []
paths:
/monitor/{monitor_id}/events:
post:
tags:
- Monitor
summary: Submit a Monitor Event
description: >
Use this endpoint to submit a model input and output pair to a monitor
for evaluation
parameters:
- name: monitor_id
in: path
description: The ID of the monitor associated with this event.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
model_input:
type: object
description: >
A dictionary of inputs sent to the LLM to generate output.
The dictionary must contain a `user_prompt` field. For
ground_truth_adherence guardrail metric, `ground_truth`
should be provided.
properties:
system_prompt:
type: string
description: The system prompt used to generate the output.
user_prompt:
type: string
description: The user prompt used to generate the output.
ground_truth:
type: string
description: >-
The ground truth for evaluating Ground Truth Adherence
guardrail.
context:
type: array
description: >-
Any structured information that directly relates to the
model’s input and expected output—e.g., the recent
turn-by-turn history between an AI tutor and a student,
facts or state passed through an agentic workflow, or
other domain-specific signals your system already knows
and wants the model to condition on.
items:
type: object
properties:
role:
type: string
description: The role of the speaker.
example: user
content:
type: string
description: The content of the message.
required:
- user_prompt
additionalProperties: false
model_output:
type: string
description: Output generated by the LLM to be evaluated.
run_mode:
type: string
description: >
Run mode for the monitor event. The run mode allows the
user to optimize for speed, accuracy, and cost by
determining which models are used to evaluate the event.
Available run modes (fastest to most thorough):
`super_fast`, `fast`, `precision`, `precision_codex`,
`precision_max`, and `precision_max_codex`. Defaults to
`fast`. Note: `super_fast` does not support Web Search or
File Search — if your monitor has these capabilities
enabled, use a different run mode or edit the monitor to
disable them.
enum:
- super_fast
- fast
- precision
- precision_codex
- precision_max
- precision_max_codex
nametag:
type: string
description: An optional, user-defined tag for the event.
required:
- model_input
- model_output
responses:
'200':
description: Monitor event created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/MonitorEventResponse'
'400':
description: Invalid request
'401':
description: Unauthorized
'404':
description: Monitor not found
security:
- BearerAuth: []
x-codeSamples:
- lang: python
label: Submit a Monitor Event
source: |
from deeprails import DeepRails
DEEPRAILS_API_KEY = "YOUR_API_KEY"
client = DeepRails(
api_key=DEEPRAILS_API_KEY,
)
monitor_response = client.monitor.submit_event(
monitor_id="mon_xxxxxxxxxxxx",
model_input={
"user_prompt": "What is the capital of France?"
},
model_output="Paris",
run_mode="fast"
)
print(monitor_response)
components:
schemas:
MonitorEventResponse:
type: object
properties:
event_id:
type: string
description: A unique monitor event ID.
example: evt_xxxxxxxxxxxx
monitor_id:
type: string
description: Monitor ID associated with this event.
example: mon_xxxxxxxxxxxx
created_at:
type: string
format: date-time
description: The time the monitor event was created in UTC.
example: '2025-01-15T10:30:00Z'
required:
- event_id
- monitor_id
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````