Post-run Checks

​

Overview

• the file you expected
• the screenshot you expected
• the structured output you expected
• the semantic result you expected

​

Why They Exist

• A report download workflow may finish, but the PDF might never have been exported.
• A form-submission workflow may end on a confirmation page, but you may want a saved screenshot as proof.
• A data-extraction workflow may produce output_data, but you may still want to verify that the contents are complete and sensible.

​

Where They Live

• you configure them once on the workflow
• every new run of that workflow can inherit them
• the run stores a snapshot of the effective checks it started with

​

When They Run

1. The main workflow execution runs first.
2. If the run has eligible Post-run Checks, the run enters running_checks, which appears in the UI as Running Checks.
3. Cyberdesk executes the checks after the main run finishes.
4. The final terminal status is decided only after those checks complete.

​

Standalone Runs vs Sessions and Chains

• Standalone runs usually release the machine before Post-run Checks begin.
• Session and chain runs can keep the machine/session claimed until Post-run Checks finish.

​

What Post-run Checks Are Not

​

The Four Initial Check Types

​

1. Attachment Exists

• exported PDFs
• CSVs
• generated files
• saved screenshots
• one-file-per-item loop workflows

​

2. Image Check

• confirmation screenshots
• chart screenshots
• receipts
• dashboards
• visual QA

• “Verify the screenshot shows a successful payment confirmation and a visible confirmation number.”
• “Verify the saved chart shows the last 30 days and includes all four vital signs.”

​

3. Output Data Passes Schema Validation

• required fields exist
• data shape is valid
• types line up with your schema

​

4. Output Data Check

• “Verify that every extracted invoice line item has a positive amount.”
• “Verify the structured output clearly identifies a patient MRN and appointment date.”
• “Verify the extracted order looks complete and not partially parsed.”

​

Attachment Targeting Modes

​

Exact Filenames

• invoice.pdf
• confirmation.png
• daily_report.csv

• stable filenames
• deterministic exports
• named screenshots

​

Exact Mode Behavior

• You provide one or more filenames.
• Filenames should include file extensions.
• At runtime, Cyberdesk looks for those exact attachment filenames.
• If a required attachment is missing, the check fails.

​

Regex

• ^invoice_.*\.pdf$
• ^receipt_[0-9]{8}\.png$
• ^export_.*\.csv$

• timestamps
• generated IDs
• date-based filenames
• dynamic naming conventions

​

Regex Mode Behavior

• Matching is done against the attachment filename.
• Matching is full-string and case-sensitive.
• Zero matches fail the check.
• You can optionally specify an expected match count.

• a literal integer
• a variable/reference that resolves to an integer
• a variable/reference that resolves to an array, in which case Cyberdesk uses the array length

​

Loop Items

• receipt_{{loop_item.name}}.png
• claim_{{loop_item.claim_id}}.pdf
• summary_{{loop_item}}.csv

• one-file-per-item workflows
• iterating over arrays
• exporting a file for each selected record

​

Loop Items Mode Behavior

• loop_input
• loop_item_filename_template

• a JSON array means “iterate over this array”
• an integer n means “iterate over items 0..n-1”

​

Producing Attachments That Checks Can Validate

​

For screenshots

• confirmation pages
• receipts
• dashboards
• visual evidence

​

For files created or downloaded on the machine

• PDFs
• CSVs
• generated documents
• downloaded exports

​

Writing Good Check Prompts

• Image Check
• Output Data Check

​

Good prompt characteristics

• State the pass condition clearly.
• Mention the evidence that matters.
• Say what should count as failure.
• Avoid asking the model to judge unrelated parts of the workflow.

​

Better Image Check Prompt

Verify the screenshot shows a successful submission confirmation. The page should
include a visible confirmation number and should not show any validation or error
messages.

​

Better Output Data Check Prompt

Verify the output data looks complete. Every invoice line item should have a
description, quantity, unit price, and positive total amount.

​

Weaker Prompts to Avoid

Check that this looks good.

Make sure nothing is wrong.

​

How Statuses Work

• the automation steps may be finished
• the run is not terminal yet
• Cyberdesk is still verifying the outcome

​

Final status behavior

• all checks pass → final run status is success
• one or more checks fail → final run ends on a failure path
• a check hits an infrastructure-level problem → final run ends on error

• Cyberdesk can still record Post-run Check results for observability
• the final run status stays on that failure path

• cancelled before checks start → checks are skipped
• cancelled during Running Checks → unfinished checks are cancelled

​

Accessing Results in Code

• get_run
• run_complete webhook payloads
• list_runs when you request fields=post_run_checks

• run.post_run_checks is an array, not an object keyed by check name
• each item includes name, status, error_message, messages, and matched_filenames
• if you want to look checks up by name, keep those names stable and unique within the workflow
• the best place to react automatically is the run_complete webhook, because it fires only after Post-run Checks finish

const checks = run.post_run_checks ?? []

const checksByName = new Map(
  checks.filter((check) => check.name).map((check) => [check.name!, check]),
)

const invoiceCheck = checksByName.get("Invoice PDF exists")

if (invoiceCheck && invoiceCheck.status !== "success") {
  console.log("status:", invoiceCheck.status)
  console.log("error:", invoiceCheck.error_message)
  console.log("messages:", invoiceCheck.messages)
  console.log("matched files:", invoiceCheck.matched_filenames)
}

checks = run.post_run_checks or []
checks_by_name = {check.name: check for check in checks if check.name}

invoice_check = checks_by_name.get("Invoice PDF exists")
status = getattr(invoice_check.status, "value", invoice_check.status) if invoice_check else None

if invoice_check and status != "success":
    print("status:", status)
    print("error:", invoice_check.error_message)
    print("messages:", invoice_check.messages)
    print("matched files:", invoice_check.matched_filenames)

​

Example End-to-End Pattern

1. downloads an invoice PDF
2. saves a confirmation screenshot
3. extracts structured invoice data

• Attachment Exists
  • exact filename: invoice.pdf
• Image Check
  • exact filename: invoice_confirmation.png
  • prompt: “Verify the screenshot shows a successful invoice export with no visible errors.”
• Output Data Passes Schema Validation
  • auto-managed because the workflow has an output schema
• Output Data Check
  • prompt: “Verify the structured output contains invoice number, invoice date, vendor name, and a positive total.”

• deterministic checks on concrete artifacts
• semantic checks on the final output

​

Best Practices

1. Prefer exact filenames when names are stable.
2. Use regex only when the variability is real and predictable.
3. Use loop_items when the workflow intentionally produces one attachment per item.
4. Pair schema validation with output data checks when you care about both shape and meaning.
5. Keep AI check prompts narrow and specific.
6. Treat Post-run Checks as verification, not as a substitute for good workflow instructions.
7. Review check results in run details when tuning a workflow.

​

Related Docs

• Save Screenshot as Run Attachment
  Learn how to create screenshot attachments that image checks can evaluate.
• Mark File for Export
  Learn how to export files from the machine as run attachments.
• Looping Tools
  Learn how start_loop, {{loop_item}}, and loop inputs work.
• Generating Output Data
  Learn how output schemas and output_data are produced and validated.
• Declare Task Succeeded
  Learn how early success detection during main execution differs from post-run verification.