> ## 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 an Event's Details
> Use this endpoint to retrieve a specific event of a guardrail workflow
Workflow events can include a whole series of improvement attempts and corresponding evaluations when the initial evaluation fails one or more metrics. Poll this endpoint for these details, plus the completion `status`, whether the output needed to be `filtered` out, the `improved_model_output` if it needed remediation, and more.
The `filtered` field is set to `true` when the event fails one or more metrics on the most recent evaluation and is set to `false` if all metric evaluations were above their thresholds. If `filtered` is `true`, then an improvement attempt will begin immediately after the initial evaluation concludes.
The `evaluation_history` field is an array of the details for each evaluation performed for the event. It can be used to track the progress of the event and see how DeepRails improved your model output over time.
The `analysis_of_failures` and `key_improvements` fields summarize the failings of the model output and the relevant changes of the improvement attempt at each step. These fields are returned for each evaluation, except the final one, and summaries of all of failures and improvements are returned in the `analysis_of_failures` and `key_improvements` fields of the event response.
## OpenAPI
````yaml /api-reference/openapi.yaml get /defend/{workflow_id}/events/{event_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:
/defend/{workflow_id}/events/{event_id}:
get:
tags:
- Defend
summary: Retrieve an Event's Details
description: |
Use this endpoint to retrieve a specific event of a guardrail workflow
parameters:
- name: workflow_id
in: path
description: The ID of the workflow associated with the event.
required: true
schema:
type: string
- name: event_id
in: path
description: The ID of the requested workflow event.
required: true
schema:
type: string
responses:
'200':
description: Workflow event details retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowEventDetailResponse'
'401':
description: Unauthorized
'404':
description: Event not found
security:
- BearerAuth: []
x-codeSamples:
- lang: python
label: Retrieve an Event's Details
source: |
from deeprails import DeepRails
DEEPRAILS_API_KEY = "YOUR_API_KEY"
client = DeepRails(
api_key=DEEPRAILS_API_KEY,
)
event_response = client.defend.retrieve_event(
workflow_id="wkfl_xxxxxxxxxxxx",
event_id="evt_xxxxxxxxxxxx",
)
print(event_response)
- lang: python
- lang: python
label: Poll a Workflow Event for Completion
source: |
from deeprails import DeepRails
client = DeepRails(
api_key=DEEPRAILS_API_KEY,
)
event_status = ""
event_response = None
while event_status != "Completed":
event_response = client.defend.retrieve_event(
workflow_id="wkfl_xxxxxxxxxxxx",
event_id="evt_xxxxxxxxxxxx",
)
event_status = event_response.status
tool_status = event_response.improvement_tool_status
if tool_status == "improved":
print(f"Improved model output: {event_response.improved_model_output}")
elif tool_status == "improvement_failed":
print(f"Improvement action failed to improve output")
elif tool_status == "no_improvement_required":
print(f"Improvement not needed!")
components:
schemas:
WorkflowEventDetailResponse:
type: object
properties:
workflow_id:
type: string
description: Workflow ID associated with the event.
example: wkfl_xxxxxxxxxxxx
event_id:
type: string
description: A unique workflow event ID.
example: evt_xxxxxxxxxxxx
status:
type: string
description: Status of the event.
example: Completed
enum:
- In Progress
- Completed
improvement_action:
type: string
description: Type of improvement action used to improve the event.
example: fixit
enum:
- regen
- fixit
- do_nothing
max_improvement_attempts:
type: integer
description: >-
The maximum number of improvement attempts to be applied to one
event before it is considered failed.
example: 10
threshold_type:
type: string
enum:
- custom
- automatic
description: Type of thresholds used to evaluate the event.
example: custom
automatic_hallucination_tolerance_levels:
type: object
description: >-
Mapping of guardrail metric names to tolerance values. Values are
strings (`low`, `medium`, `high`) representing automatic tolerance
levels.
example: null
additionalProperties:
type: string
enum:
- low
- medium
- high
custom_hallucination_threshold_values:
type: object
description: >-
Mapping of guardrail metric names to threshold values. Values are
floating point numbers (0.0-1.0) representing custom thresholds.
example:
completeness: 0.8
instruction_adherence: 0.8
additionalProperties:
type: number
format: float
minimum: 0
maximum: 1
capabilities:
type: array
description: >-
Extended AI capabilities available to the event, if any. Can be
`web_search`, `file_search`, and/or `context_awareness`.
items:
type: object
properties:
capability:
type: string
example:
- capability: web_search
- capability: file_search
- capability: context_awareness
files:
type: array
description: >-
List of files available to the event, if any. Will only be present
if `file_search` is enabled.
items:
type: object
properties:
file_name:
type: string
example: example.pdf
file_id:
type: string
example: file_xxxxxxxxxxxx
file_size:
type: integer
example: 1024
presigned_url:
type: string
example: https://deeprails.com/files/example.pdf
presigned_url_expires_at:
type: string
format: date-time
example: '2025-11-10T01:32:44.591Z'
filtered:
type: boolean
description: Whether the event was filtered and requires improvement.
example: false
improvement_tool_status:
type: string
nullable: true
description: >-
Status of the improvement tool used to improve the event.
`improvement_required` indicates that the evaluation is complete and
the improvement action is needed but is not taking place. `improved`
and `improvement_failed` indicate when the improvement action
concludes, successfully and unsuccessfully, respectively.
`no_improvement_required` means that the first evaluation passed all
its metrics!
example: improved
enum:
- improved
- improvement_failed
- no_improvement_required
- improvement_required
improved_model_output:
type: string
description: >-
Improved model output after improvement tool was applied and each
metric passed evaluation.
example: >-
Mitosis creates haploid gametes for reproduction, while meiosis
produces identical diploid cells for growth.
evaluation_result:
type: object
description: >-
Evaluation result consisting of average scores and rationales for
each of the evaluated guardrail metrics.
additionalProperties: true
example:
completeness:
score: 0.89
rationale: >-
The sentence is concise, relevant, and well-structured, and it
covers the main differences (cell number, genetic similarity,
ploidy, and biological role) appropriate to a one-sentence
answer. However, it overgeneralizes and makes unqualified
universal claims: stating mitosis produces 'diploid' cells and
meiosis produces 'four ... gametes' can be inaccurate in some
biological contexts (e.g., mitosis in haploid cells or
organisms, and oogenesis producing one functional ovum plus
polar bodies). To make the sentence both accurate and still
compact, add brief qualifiers—for example: 'In diploid
organisms, mitosis produces two genetically similar diploid
daughter cells for growth and repair, whereas meiosis involves
two divisions that typically yield four genetically varied
haploid cells (gametes), although in female animals often only
one functional gamete results.' This preserves brevity while
removing the main factual overgeneralizations.
threshold: 0.8
instruction_adherence:
score: 1
rationale: >-
The response exemplary meets the explicit instructions by
delivering a single, well-formed sentence that clearly contrasts
mitosis and meiosis using key distinguishing features (cell
number, genetic identity/variation, ploidy, and biological
purpose), showing concise and accurate adherence to the prompt.
threshold: 0.8
evaluation_history:
type: array
description: History of evaluations for the event.
items:
type: object
properties:
attempt:
type: string
example: Initial Evaluation
evaluation_status:
type: string
example: completed
improvement_tool_status:
type: string
example: improvement_required
enum:
- improved
- improvement_failed
- no_improvement_required
- improvement_required
analysis_of_failures:
type: string
example: >-
The response is concise, and well-structured, but it does not
cover the main differences (cell number, genetic similarity,
ploidy, and biological role) appropriate to a one-sentence
answer.
key_improvements:
type: array
items:
type: string
example:
- >-
Added a brief qualifier to the sentence to make it more
accurate.
- >-
Added a more detailed explanation of the differences between
mitosis and meiosis.
guardrail_metrics:
type: array
items:
type: string
example:
- completeness
- instruction_adherence
run_mode:
type: string
example: precision
model_input:
type: object
additionalProperties: true
example:
system_prompt: You are a helpful tutor specializing in AP science classes.
user_prompt: >-
Explain the difference between mitosis and meiosis in one
sentence.
context:
- role: user
content: I have an AP Bio exam tomorrow, can you help me study?
- role: tutor
content: Sure, I'll help you study.
model_output:
type: string
example: >-
Mitosis creates haploid gametes for reproduction, while
meiosis produces identical diploid cells for growth.
nametag:
type: string
example: Test Event
progress:
type: integer
example: 100
error_message:
type: string
example: null
evaluation_result:
type: object
additionalProperties: true
example:
correctness:
score: 1
rationale: >-
The response correctly and concisely summarizes core
features of franchise agreements.
threshold: 0.9
completeness:
score: 0.9166666666666667
rationale: >-
The AI response is accurate, well-organized, and directly
addresses both parts of the user's request (it correctly
requests the file and gives a clear overview of franchise
agreements). The primary shortcoming is depth: the reply
is a solid preliminary checklist but does not provide
clause-level detail, jurisdiction-specific guidance,
sample language, numerical norms (e.g., typical royalty
percentages or fee ranges by industry), or prioritized
negotiation strategies that would be expected for a
high-standard explanatory review.
threshold: 0.8
evaluation_total_cost:
type: number
format: float
example: 0.03
created_at:
type: string
format: date-time
example: '2025-01-15T10:30:00Z'
example:
- attempt: Initial Evaluation
evaluation_status: completed
improvement_tool_status: improvement_required
analysis_of_failures: >-
The response is concise, and well-structured, but it does not
cover the main differences (cell number, genetic similarity,
ploidy, and biological role) appropriate to a one-sentence
answer.
key_improvements:
- >-
Added a brief qualifier to the sentence to make it more
accurate.
- >-
Added a more detailed explanation of the differences between
mitosis and meiosis.
guardrail_metrics:
- completeness
- instruction_adherence
run_mode: precision
model_input:
user_prompt: >-
Explain the difference between mitosis and meiosis in one
sentence.
context:
- role: user
content: I have an AP Bio exam tomorrow, can you help me study?
- role: tutor
content: Sure, I'll help you study.
model_output: >-
Mitosis creates haploid gametes for reproduction, while meiosis
produces identical diploid cells for growth.
nametag: Test
progress: 100
error_message: null
evaluation_result:
completeness:
score: 0.6
rationale: >-
The response is concise, and well-structured, but it does
not cover the main differences (cell number, genetic
similarity, ploidy, and biological role) appropriate to a
one-sentence answer.
threshold: 0.8
instruction_adherence:
score: 0.25
rationale: >-
The response does not highlight the key differences between
mitosis and meiosis.
threshold: 0.8
evaluation_total_cost: 0.01
created_at: '2025-11-10T01:32:44.591Z'
- attempt: Improvement Attempt 1
evaluation_status: completed
improvement_tool_status: improved
analysis_of_failures: null
key_improvements: null
guardrail_metrics:
- completeness
- instruction_adherence
run_mode: precision
model_input:
user_prompt: >-
Explain the difference between mitosis and meiosis in one
sentence.
context:
- role: user
content: I have an AP Bio exam tomorrow, can you help me study?
- role: tutor
content: Sure, I'll help you study.
model_output: >-
Mitosis produces two genetically identical diploid cells for
growth and tissue repair, whereas meiosis generates four
genetically varied haploid gametes for sexual reproduction.
nametag: Test
progress: 100
error_message: null
evaluation_result:
completeness:
score: 0.89
rationale: >-
The sentence is concise, relevant, and well-structured, and
it covers the main differences (cell number, genetic
similarity, ploidy, and biological role) appropriate to a
one-sentence answer. However, it overgeneralizes and makes
unqualified universal claims: stating mitosis produces
'diploid' cells and meiosis produces 'four ... gametes' can
be inaccurate in some biological contexts (e.g., mitosis in
haploid cells or organisms, and oogenesis producing one
functional ovum plus polar bodies). To make the sentence
both accurate and still compact, add brief qualifiers—for
example: 'In diploid organisms, mitosis produces two
genetically similar diploid daughter cells for growth and
repair, whereas meiosis involves two divisions that
typically yield four genetically varied haploid cells
(gametes), although in female animals often only one
functional gamete results.' This preserves brevity while
removing the main factual overgeneralizations.
threshold: 0.8
instruction_adherence:
score: 1
rationale: >-
The response exemplary meets the explicit instructions by
delivering a single, well-formed sentence that clearly
contrasts mitosis and meiosis using key distinguishing
features (cell number, genetic identity/variation, ploidy,
and biological purpose), showing concise and accurate
adherence to the prompt.
threshold: 0.8
evaluation_total_cost: 0.01
created_at: '2025-11-10T01:32:44.591Z'
analysis_of_failures:
type: array
items:
type: string
example: >-
The response is concise, and well-structured, but it does not
cover the main differences (cell number, genetic similarity,
ploidy, and biological role) appropriate to a one-sentence answer.
key_improvements:
type: array
items:
type: object
example:
- '0':
- >-
Added a brief qualifier to the sentence to make it more
accurate.
- >-
Added a more detailed explanation of the differences between
mitosis and meiosis.
required:
- event_id
- workflow_id
- status
- improvement_action
- threshold_type
- filtered
- improvement_tool_status
- improved_model_output
- evaluation_result
- evaluation_history
- analysis_of_failures
- key_improvements
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````