Skip to main content
GET
/
defend
/
{workflow_id}
Retrieve a Workflow's Details
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)
{
  "workflow_id": "defend_abc123",
  "name": "Test Workflow",
  "description": "A workflow used to test the DeepRails API",
  "status": "active",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "threshold_type": "custom",
  "automatic_hallucination_tolerance_levels": null,
  "custom_hallucination_threshold_values": {
    "correctness": 0.9
  },
  "events": [
    {
      "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": [
    {
      "capability": "web_search"
    },
    {
      "capability": "file_search"
    },
    {
      "capability": "context_awareness"
    }
  ],
  "files": [
    {
      "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"
    }
  ],
  "improvement_action": "fixit",
  "stats": {
    "outputs_processed": 1,
    "outputs_below_threshold": 0,
    "outputs_improved": 0
  }
}
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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
workflow_id
string
required

The ID of the workflow to retrieve.

Query Parameters

​
limit
integer
default:10

Limit the number of returned events associated with this workflow. Defaults to 10.

Response

Workflow retrieved successfully

​
workflow_id
string
required

A unique workflow ID used to identify the workflow in other endpoints.

Example:

"defend_abc123"

​
name
string
required

A human-readable name for the workflow that will correspond to it's workflow ID.

Example:

"Test Workflow"

​
description
string
required

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
enum<string>
required

Status of the selected workflow. May be inactive or active. Inactive workflows will not accept events.

Available options:
inactive,
active
Example:

"active"

​
created_at
string<date-time>
required

The time the workflow was created in UTC.

​
updated_at
string<date-time>
required

The most recent time the workflow was updated in UTC.

​
threshold_type
enum<string>
required

Type of thresholds used to evaluate the event.

Available options:
custom,
automatic
Example:

"custom"

​
automatic_hallucination_tolerance_levels
object
required

Mapping of guardrail metric names to tolerance values. Values can be strings (low, medium, high) for automatic tolerance levels.

Example:

null

​
custom_hallucination_threshold_values
object
required

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 }
​
events
object[]
required

An array of events associated with this workflow.

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
object[]
required

Extended AI capabilities available to the event, if any. Can be web_search, file_search, and/or context_awareness.

Example:
[
  { "capability": "web_search" },
  { "capability": "file_search" },
  { "capability": "context_awareness" }
]
​
files
object[]
required

List of files associated with the workflow. If this is not empty, models can search these files when performing evaluations or remediations

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"
  }
]
​
improvement_action
enum<string>

The action used to improve outputs that fail one or more guardrail metrics for the workflow events.

Available options:
regen,
fixit,
do_nothing
Example:

"fixit"

​
stats
object