> ## 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.
# Retrieve a Monitor's Details
> Use this endpoint to retrieve the details and evaluations associated with a specific monitor
Monitors track all the data from each of the events submitted to them. This endpoint returns comprehensive information for the monitor including recent event history and observability stats, plus configuration details like `name`, `description`, and its `status`.
The `stats` object in the response has counts of the evaluations in each status and an `evaluations` array containing all evaluation records.
Use the optional `limit` query parameter to control the number of returned evaluations (defaults to 10).
## OpenAPI
````yaml /api-reference/openapi.yaml get /monitor/{monitor_id}
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}:
get:
tags:
- Monitor
summary: Retrieve a Monitor's Details
description: >
Use this endpoint to retrieve the details and evaluations associated
with a specific monitor
parameters:
- name: monitor_id
in: path
description: The ID of the monitor to retrieve.
required: true
schema:
type: string
- name: limit
in: query
description: >-
Limit the number of returned evaluations associated with this
monitor. Defaults to 10.
required: false
schema:
type: integer
default: 10
responses:
'200':
description: Monitor retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/MonitorDetailResponse'
'401':
description: Unauthorized
'404':
description: Monitor not found
security:
- BearerAuth: []
x-codeSamples:
- lang: python
label: Retrieve a monitor
source: |
from deeprails import DeepRails
DEEPRAILS_API_KEY = "YOUR_API_KEY"
client = DeepRails(
api_key=DEEPRAILS_API_KEY,
)
monitor_response = client.monitor.retrieve(
monitor_id="mon_xxxxxxxxxxxx"
)
print(monitor_response.data.name)
print(monitor_response.data.status)
components:
schemas:
MonitorDetailResponse:
type: object
properties:
monitor_id:
type: string
description: A unique monitor ID.
example: mon_xxxxxxxxxxxx
name:
type: string
description: Name of this monitor.
example: Test Monitor
description:
type: string
description: Description of this monitor.
example: A monitor used to test the DeepRails SDK
status:
type: string
description: >-
Status of the monitor. Can be `active` or `inactive`. Inactive
monitors no longer record and evaluate events.
example: active
enum:
- active
- inactive
created_at:
type: string
format: date-time
description: The time the monitor was created in UTC.
example: '2025-01-15T10:30:00Z'
updated_at:
type: string
format: date-time
description: The most recent time the monitor was modified in UTC.
example: '2025-01-15T10:30:00Z'
stats:
type: object
description: >
Contains five fields used for stats of this monitor: total
evaluations, completed evaluations, failed evaluations, queued
evaluations, and in progress evaluations.
properties:
total_evaluations:
type: integer
description: Total number of evaluations performed by this monitor.
example: 1
completed_evaluations:
type: integer
description: Number of evaluations that completed successfully.
example: 0
failed_evaluations:
type: integer
description: Number of evaluations that failed.
example: 0
queued_evaluations:
type: integer
description: Number of evaluations currently queued.
example: 0
in_progress_evaluations:
type: integer
description: Number of evaluations currently in progress.
example: 1
evaluations:
type: array
description: >-
An array of all evaluations performed by this monitor. Each one
corresponds to a separate monitor event.
items:
$ref: '#/components/schemas/EvaluationResponse'
capabilities:
type: array
description: >-
An array of extended AI capabilities associated with this monitor.
Can be `web_search`, `file_search`, and/or `context_awareness`.
items:
type: object
properties:
capability:
type: string
description: The type of capability.
example: web_search
files:
type: array
description: An array of files associated with this monitor.
items:
type: object
properties:
file_name:
type: string
description: The name of the file.
example: example.pdf
file_id:
type: string
description: The ID of the file.
example: file_xxxxxxxxxxxx
file_size:
type: integer
description: The size of the file in bytes.
example: 1024
required:
- monitor_id
- name
- status
- created_at
- updated_at
- stats
- evaluations
- capabilities
- files
EvaluationResponse:
type: object
properties:
evaluation_status:
type: string
description: Status of the evaluation.
enum:
- in_progress
- completed
- canceled
- queued
- failed
guardrail_metrics:
type: array
description: >
An array of guardrail metrics that the input and output pair will be
evaluated on.
items:
type: string
enum:
- correctness
- completeness
- instruction_adherence
- context_adherence
- ground_truth_adherence
- comprehensive_safety
run_mode:
type: string
description: >
Run mode for the evaluation. The run mode allows the user to
optimize for speed, accuracy, and cost by determining which models
are used to evaluate the event. Note: `super_fast` do not support
Web Search or File Search capabilities.
enum:
- super_fast
- fast
- precision
- precision_codex
- precision_max
- precision_max_codex
example: fast
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. When `context_awareness` is enabled, `context` should be
provided.
properties:
system_prompt:
type: string
description: The system prompt used to generate the output.
example: You are a helpful assistant.
user_prompt:
type: string
description: The user prompt used to generate the output.
example: Hello, how are you?
ground_truth:
type: string
description: >-
The ground truth for evaluating Ground Truth Adherence
guardrail.
example: >-
The user prefers that you refer to them as 'the user' instead of
'you'.
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.
example:
- role: user
content: >-
Can you help me update my code from 5 years ago to use
modern C++ practices?
required:
- user_prompt
additionalProperties: false
model_output:
type: string
description: Output generated by the LLM to be evaluated.
example: I am good, thank you!
nametag:
type: string
description: An optional, user-defined tag for the evaluation.
example: Test Evaluation
progress:
type: integer
description: >-
Evaluation progress. Values range between 0 and 100; 100
corresponds to a completed `evaluation_status`.
minimum: 0
maximum: 100
example: 50
error_message:
type: string
description: Error message if the evaluation failed.
example: null
evaluation_result:
type: object
description: >-
Evaluation result consisting of average scores and rationales for
each of the evaluated guardrail metrics.
additionalProperties: true
example: null
evaluation_total_cost:
type: number
format: float
description: Total cost of the evaluation.
example: null
created_at:
type: string
format: date-time
description: The time the evaluation was created in UTC.
example: '2025-01-15T10:30:00Z'
required:
- evaluation_status
- model_input
- model_output
- run_mode
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````