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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)
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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "improvement_tool_status": null,
      "improved_model_output": null,
      "evaluations": [
        {
          "attempt": "Initial Evaluation",
          "evaluation_status": "completed",
          "guardrail_metrics": [
            "correctness"
          ],
          "run_mode": "smart",
          "model_input": {
            "system_prompt": "You are a helpful assistant.",
            "user_prompt": "Hello, how are you?"
          },
          "model_output": "I am good, thank you!",
          "nametag": "Test Event",
          "progress": 100,
          "error_message": null,
          "evaluation_result": {
            "correctness": {
              "score": 1,
              "rationale": "The response is correct.",
              "threshold": 0.9
            }
          },
          "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"
    }
  ],
  "files": [
    {
      "file_name": "example.pdf",
      "file_id": "file_xxxxxxxx",
      "file_size": 1024
    }
  ],
  "improvement_action": "fixit",
  "stats": {
    "outputs_processed": 1,
    "outputs_below_threshold": 0,
    "outputs_improved": 0
  }
}

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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)
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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "improvement_tool_status": null,
      "improved_model_output": null,
      "evaluations": [
        {
          "attempt": "Initial Evaluation",
          "evaluation_status": "completed",
          "guardrail_metrics": [
            "correctness"
          ],
          "run_mode": "smart",
          "model_input": {
            "system_prompt": "You are a helpful assistant.",
            "user_prompt": "Hello, how are you?"
          },
          "model_output": "I am good, thank you!",
          "nametag": "Test Event",
          "progress": 100,
          "error_message": null,
          "evaluation_result": {
            "correctness": {
              "score": 1,
              "rationale": "The response is correct.",
              "threshold": 0.9
            }
          },
          "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"
    }
  ],
  "files": [
    {
      "file_name": "example.pdf",
      "file_id": "file_xxxxxxxx",
      "file_size": 1024
    }
  ],
  "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.

Show child attributes

automatic_hallucination_tolerance_levels.{key}

enum<string>

Available options:

low,

medium,

high

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.

Show child attributes

custom_hallucination_threshold_values.{key}

number<float>

Required range: 0 <= x <= 1

Example:

{ "correctness": 0.9 }

events

object[]

required

An array of events associated with this workflow.

Show child attributes

events.event_id

string

A unique workflow event ID.

Example:

"wkfl_evt_def456"

events.improvement_tool_status

string

Status of the improvement tool used to improve the event.

Example:

null

events.improved_model_output

string

Improved model output after improvement tool was applied.

Example:

null

events.evaluations

object[]

An array of evaluations for this event.

Show child attributes

events.evaluations.attempt

string

The attempt number or identifier for this evaluation.

Example:

"Initial Evaluation"

events.evaluations.evaluation_status

string

Status of the evaluation.

Example:

"completed"

events.evaluations.guardrail_metrics

string[]

An array of guardrail metrics evaluated.

events.evaluations.run_mode

string

Run mode used for the evaluation.

Example:

"smart"

events.evaluations.model_input

object

The model input used for the evaluation.

Example:

{
  "system_prompt": "You are a helpful assistant.",
  "user_prompt": "Hello, how are you?"
}

events.evaluations.model_output

string

The model output that was evaluated.

Example:

"I am good, thank you!"

events.evaluations.nametag

string

An optional tag for the evaluation.

Example:

"Test Event"

events.evaluations.progress

integer

Evaluation progress (0-100).

Example:

100

events.evaluations.error_message

string

Error message if the evaluation failed.

Example:

null

events.evaluations.evaluation_result

object

The result of the evaluation.

Example:

{
  "correctness": {
    "score": 1,
    "rationale": "The response is correct.",
    "threshold": 0.9
  }
}

events.evaluations.evaluation_total_cost

number<float>

Total cost of the evaluation.

Example:

0.01

events.evaluations.created_at

string<date-time>

The time the evaluation was created in UTC.

Example:

"2025-11-10T01:32:44.591Z"

events.evaluations.modified_at

string<date-time>

The time the evaluation was last modified in UTC.

Example:

"2025-11-10T01:32:44.591Z"

Example:

[
  {
    "event_id": "evt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "improvement_tool_status": null,
    "improved_model_output": null,
    "evaluations": [
      {
        "attempt": "Initial Evaluation",
        "evaluation_status": "completed",
        "guardrail_metrics": ["correctness"],
        "run_mode": "smart",
        "model_input": {
          "system_prompt": "You are a helpful assistant.",
          "user_prompt": "Hello, how are you?"
        },
        "model_output": "I am good, thank you!",
        "nametag": "Test Event",
        "progress": 100,
        "error_message": null,
        "evaluation_result": {
          "correctness": {
            "score": 1,
            "rationale": "The response is correct.",
            "threshold": 0.9
          }
        },
        "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 and/or file_search.

Show child attributes

capabilities.capability

string

Example:

"web_search"

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

Show child attributes

files.file_name

string

files.file_id

string

files.file_size

integer

Example:

[
  {
    "file_name": "example.pdf",
    "file_id": "file_xxxxxxxx",
    "file_size": 1024
  }
]

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

Show child attributes

stats.outputs_processed

integer

Total number of AI outputs processed by the workflow.

Example:

1

stats.outputs_below_threshold

integer

Number of AI outputs that failed the guardrails.

Example:

0

stats.outputs_improved

integer

Number of AI outputs that were improved.

Example:

0

Create a Workflow Update a Workflow

⌘I

API Documentation

Authorizations

Path Parameters

Query Parameters

Response