Retrieve an Event's Details

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

{
  "workflow_id": "wkfl_xxxxxxxxxxxx",
  "event_id": "evt_xxxxxxxxxxxx",
  "status": "Completed",
  "improvement_action": "fixit",
  "threshold_type": "custom",
  "filtered": false,
  "improvement_tool_status": "improved",
  "improved_model_output": "Mitosis creates haploid gametes for reproduction, while meiosis produces identical diploid cells for growth.",
  "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_history": [
    {
      "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": [
    "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": [
    {
      "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."
      ]
    }
  ],
  "max_improvement_attempts": 10,
  "automatic_hallucination_tolerance_levels": null,
  "custom_hallucination_threshold_values": {
    "completeness": 0.8,
    "instruction_adherence": 0.8
  },
  "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"
    }
  ]
}

GET

defend

{workflow_id}

events

{event_id}

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

{
  "workflow_id": "wkfl_xxxxxxxxxxxx",
  "event_id": "evt_xxxxxxxxxxxx",
  "status": "Completed",
  "improvement_action": "fixit",
  "threshold_type": "custom",
  "filtered": false,
  "improvement_tool_status": "improved",
  "improved_model_output": "Mitosis creates haploid gametes for reproduction, while meiosis produces identical diploid cells for growth.",
  "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_history": [
    {
      "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": [
    "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": [
    {
      "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."
      ]
    }
  ],
  "max_improvement_attempts": 10,
  "automatic_hallucination_tolerance_levels": null,
  "custom_hallucination_threshold_values": {
    "completeness": 0.8,
    "instruction_adherence": 0.8
  },
  "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"
    }
  ]
}

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.

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 associated with the event.

event_id

string

required

The ID of the requested workflow event.

Response

Workflow event details retrieved successfully

workflow_id

string

required

Workflow ID associated with the event.

Example:

"wkfl_xxxxxxxxxxxx"

event_id

string

required

A unique workflow event ID.

Example:

"evt_xxxxxxxxxxxx"

status

enum<string>

required

Status of the event.

Available options:

In Progress,

Completed

Example:

"Completed"

improvement_action

enum<string>

required

Type of improvement action used to improve the event.

Available options:

regen,

fixit,

do_nothing

Example:

"fixit"

threshold_type

enum<string>

required

Type of thresholds used to evaluate the event.

Available options:

custom,

automatic

Example:

"custom"

filtered

boolean

required

Whether the event was filtered and requires improvement.

Example:

false

improvement_tool_status

enum<string> | null

required

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!

Available options:

improved,

improvement_failed,

no_improvement_required,

improvement_required

Example:

"improved"

improved_model_output

string

required

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

object

required

Evaluation result consisting of average scores and rationales for each of the evaluated guardrail metrics.

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

object[]

required

History of evaluations for the event.

Show child attributes

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

string[]

required

key_improvements

object[]

required

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."
    ]
  }
]

max_improvement_attempts

integer

The maximum number of improvement attempts to be applied to one event before it is considered failed.

Example:

10

automatic_hallucination_tolerance_levels

object

Mapping of guardrail metric names to tolerance values. Values are strings (low, medium, high) representing automatic tolerance levels.

Show child attributes

Example:

null

custom_hallucination_threshold_values

object

Mapping of guardrail metric names to threshold values. Values are floating point numbers (0.0-1.0) representing custom thresholds.

Show child attributes

Example:

{
  "completeness": 0.8,
  "instruction_adherence": 0.8
}

capabilities

object[]

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

Show child attributes

Example:

[
  { "capability": "web_search" },
  { "capability": "file_search" },
  { "capability": "context_awareness" }
]

files

object[]

List of files available to the event, if any. Will only be present if file_search is enabled.

Show child attributes

Submit a Workflow Event Stream a Workflow Event (Optimized)