> ## 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 Workflow's Details
> Use this endpoint to retrieve the details for a specific defend workflow
Workflows will eventually contain many events, each with its own set of evaluations and improvement attempts. Many of the details of these events can be viewed in the Defend Data tab in the DeepRails console, but you can also see configuration details when polling this endpoint.
The `status` field indicates whether the workflow is active and currently accepting events. If the workflow status is `inactive`, no events submitted for the workflow will be processed.
The `stats` field contains counts of the events processed by the workflow, which can be used to determine the efficacy of the workflow. The `events` field lists the details of the most recent events processed by the workflow in a format similar to what is returned when you retrieve an event's details.
## OpenAPI
````yaml /api-reference/openapi.yaml get /defend/{workflow_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}:
get:
tags:
- Defend
summary: Retrieve a Workflow's Details
description: |
Use this endpoint to retrieve the details for a specific defend workflow
parameters:
- name: workflow_id
in: path
description: The ID of the workflow to retrieve.
required: true
schema:
type: string
- name: limit
in: query
description: >-
Limit the number of returned events associated with this workflow.
Defaults to 10.
required: false
schema:
type: integer
default: 10
responses:
'200':
description: Workflow retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DefendResponse'
'401':
description: Unauthorized
'404':
description: Workflow not found
security:
- BearerAuth: []
x-codeSamples:
- lang: python
label: Retrieve a Workflow's Details
source: |
from deeprails import DeepRails
DEEPRAILS_API_KEY = "YOUR_API_KEY"
client = DeepRails(
api_key=DEEPRAILS_API_KEY,
)
workflow_response = client.defend.retrieve_workflow(
workflow_id="wkfl_xxxxxxxxxxxx"
)
print(workflow_response)
components:
schemas:
DefendResponse:
type: object
properties:
workflow_id:
type: string
description: >-
A unique workflow ID used to identify the workflow in other
endpoints.
example: defend_abc123
name:
type: string
description: >-
A human-readable name for the workflow that will correspond to it's
workflow ID.
example: Test Workflow
nullable: false
description:
type: string
description: >-
A description for the workflow, to help you remember what that
workflow means to your organization.
example: A workflow used to test the DeepRails API
status:
type: string
description: >-
Status of the selected workflow. May be `inactive` or `active`.
Inactive workflows will not accept events.
example: active
enum:
- inactive
- active
improvement_action:
type: string
description: >-
The action used to improve outputs that fail one or more guardrail
metrics for the workflow events.
example: fixit
enum:
- regen
- fixit
- do_nothing
created_at:
type: string
format: date-time
description: The time the workflow was created in UTC.
updated_at:
type: string
format: date-time
description: The most recent time the workflow was updated in UTC.
stats:
type: object
properties:
outputs_processed:
type: integer
description: Total number of AI outputs processed by the workflow.
example: 1
outputs_below_threshold:
type: integer
description: Number of AI outputs that failed the guardrails.
example: 0
outputs_improved:
type: integer
description: Number of AI outputs that were improved.
example: 0
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 can be
strings (`low`, `medium`, `high`) for 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 can be
floating point numbers (0.0-1.0) for custom thresholds.
example:
correctness: 0.9
additionalProperties:
type: number
format: float
minimum: 0
maximum: 1
events:
type: array
description: An array of events associated with this workflow.
items:
type: object
properties:
event_id:
type: string
description: A unique workflow event ID.
example: wkfl_evt_def456
status:
type: string
description: Status of the event.
example: completed
enum:
- completed
- failed
- in_progress
improvement_tool_status:
type: string
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.
example: >-
Mitosis produces two genetically identical diploid cells for
growth and tissue repair, whereas meiosis generates four
genetically varied haploid gametes for sexual reproduction.
billing_request_id:
type: string
description: The ID of the billing request for the event.
example: bill_0123456789abcdefabcd
evaluations:
type: array
description: An array of evaluations for this event.
items:
type: object
properties:
attempt:
type: string
description: The attempt number or identifier for this evaluation.
example: Improvement Attempt 1
evaluation_status:
type: string
description: Status of the evaluation.
example: completed
improvement_tool_status:
type: string
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: improvement_required
enum:
- improved
- improvement_failed
- no_improvement_required
- improvement_required
analysis_of_failures:
type: string
description: >-
Analysis of the failures of the model_output according
to the guardrail metrics evaluated.
example: >-
The model output does not cover the main differences
(cell number, genetic similarity, ploidy, and biological
role) appropriate to a one-sentence answer.
key_improvements:
type: array
description: >-
A list of key improvements made to the model_output to
address the failures.
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
description: An array of guardrail metrics evaluated.
items:
type: string
example: completeness, instruction_adherence
run_mode:
type: string
description: Run mode used for the evaluation.
example: precision
model_input:
type: object
description: The model input used for the evaluation.
additionalProperties: true
example:
user_prompt: >-
Explain the difference between mitosis and meiosis in
one sentence.
model_output:
type: string
description: The model output that was evaluated.
example: >-
Mitosis creates haploid gametes for reproduction, while
meiosis produces identical diploid cells for growth.
nametag:
type: string
description: An optional tag for the evaluation.
example: Test Event
progress:
type: integer
description: Evaluation progress (0-100).
example: 100
error_message:
type: string
description: Error message if the evaluation failed.
example: null
evaluation_result:
type: object
description: The result of the evaluation.
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: ''
threshold: 0.8
evaluation_total_cost:
type: number
format: float
description: Total cost of the evaluation.
example: 0.01
created_at:
type: string
format: date-time
description: The time the evaluation was created in UTC.
example: '2025-11-10T01:32:44.591Z'
modified_at:
type: string
format: date-time
description: The time the evaluation was last modified in UTC.
example: '2025-11-10T01:32:44.591Z'
example:
- event_id: evt_xxxxxxxxxxxx
status: completed
improvement_tool_status: improved
improved_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.
billing_request_id: bill_0123456789abcdefabcd
evaluations:
- 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:
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: >-
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:
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: >-
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'
modified_at: '2025-11-10T01:32:44.591Z'
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: web_search
example:
- capability: web_search
- capability: file_search
- capability: context_awareness
files:
type: array
description: >-
List of files associated with the workflow. If this is not empty,
models can search these files when performing evaluations or
remediations
items:
type: object
properties:
file_name:
type: string
file_id:
type: string
file_size:
type: integer
presigned_url:
type: string
presigned_url_expires_at:
type: string
format: date-time
example:
- file_name: example.pdf
file_id: file_xxxxxxxxxxxx
file_size: 1024
presigned_url: https://deeprails.com/files/example.pdf
presigned_url_expires_at: '2025-11-10T01:32:44.591Z'
required:
- workflow_id
- name
- description
- status
- created_at
- updated_at
- threshold_type
- automatic_hallucination_tolerance_levels
- custom_hallucination_threshold_values
- capabilities
- files
- events
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````