In Prefect, what does create_markdown_artifact attach to a flow run?

## What an artifact is An **artifact** in Prefect is a small, structured, human-facing record attached to a flow run or task run and rendered in the UI. Logs answer "what happened, line by line"; artifacts answer "what should a person look at when this run finishes". They are published from inside your code by calling a helper, which associates the payload with whichever run is currently executing. ## The helpers - `create_markdown_artifact(markdown=..., key=..., description=...)` — a formatted block: headings, bullets, tables, bold numbers. - `create_link_artifact(link=..., link_text=..., key=...)` — a clickable URL, ideal for the dashboard, the report file, or the warehouse query this run produced. - `create_table_artifact(table=..., key=...)` — a list of dicts (or a dict of lists) rendered as a table, good for a small preview or a per-partition row count. - `create_progress_artifact(...)` with `update_progress_artifact(...)` — a progress indicator for a long loop, so an operator can see how far a run has got without reading logs. All of them are called from inside a `@flow` or `@task` body; the current run context is what ties the artifact to the run. ```python from prefect import flow from prefect.artifacts import create_markdown_artifact @flow def nightly(): rows, nulls = load() create_markdown_artifact( key="nightly-dq-report", markdown=f"# Nightly load\n\n- rows: **{rows}**\n- null keys: **{nulls}**", description="Row and null counts for the nightly orders load", ) ``` ## Why the key matters Without a `key`, the artifact is simply attached to that one run and you find it by opening the run. With a `key`, Prefect treats successive publications as **versions of the same artifact**: the UI gives the key its own page listing every version with the run that produced it. That turns a one-off summary into a time series a human can scan — last night's row count next to the previous seven, the freshness check that has been drifting, the link to each run's output file. Keys are meant to be stable, lowercase, dash-separated identifiers; changing the key starts a new history. ## Where artifacts live Artifacts are stored with run metadata in the Prefect API — the same place states, logs and run records live — not in the result storage where persisted task results go. Two consequences follow. First, size discipline: a markdown artifact is a summary, not a data dump; publishing thousands of rows per run bloats the metadata store and makes the UI unpleasant. Second, sensitivity: anything you put in an artifact is visible to everyone who can see the workspace, and in Prefect Cloud it leaves your infrastructure in a way that persisted result *data* deliberately does not. Never publish credentials, tokens, or raw customer records; publish counts, ratios, and links to where the real data sits. ## When to reach for an artifact rather than a log Use a log line for the running narrative — "connected", "read 12 files", "retrying". Use an artifact when a person will want the summary *after* the run, or will want to compare it against previous runs: data-quality checks, validation results, a diff of what a job would change, the URL of the report it wrote, the parameters of a model it trained. A well-run Prefect deployment typically publishes one keyed artifact per meaningful run outcome, and operators learn to open that page instead of scrolling logs. ## Artifacts and states Artifacts are independent of state transitions — they are not hooks and do not affect whether a run is Completed or Failed. It is common and useful to publish one on the failure path too (inside an `on_failure` hook or an `except` branch), so the run that failed carries a readable explanation of *what* it found rather than only a traceback. Because publication is a normal call inside your code, an artifact is only written if the code reaches it: a Crashed run publishes nothing, which is another reason durable alerting belongs in server-side automations rather than in the artifact itself.