Running a Stream
Stream mode is beta and under active development. The flow below is the shipped one, but expect bugs, and expect the screen to change between releases as the known limitations are worked through. Treat a live stream as a view onto the run rather than the authoritative record of it: keep MinKNOW’s output, and expect to finish with the normal Discover & Associate pass once the run ends.
Streams live on a sequencing order. Open the order, choose Sequencing Data
in the sidebar, then Stream (/orders/{id}/sequencing?view=stream). The page
is facility-admin only.
The header card, Live sequencer stream, is badged Active while a stream is receiving, Stopping between your click on Stop receiving and the daemon converting the run, Stopped when you are looking at a finished run, and Idle only when the sequencing order has never had a stream at all. The Start receiving form appears whenever no stream is active — including while you are reading a stopped one — and the counters and panels below describe whichever run is selected.
Starting
Check the daemon before you type anything
Next to the Start receiving button, the page reports the stream-monitor
daemon’s state. Green means running, with its PID. Amber means stopped or
errored, with an inline Start daemon button and a Settings link. Starting
a stream while the daemon is down succeeds and then does nothing at all, which
is the single most common way to waste a run.
Enter the output directory
Give the run folder — the one that contains fastq_pass/, fastq_fail/ and
pod5/. MinKNOW prints it under Output on its Run Setup screen. If you did
not change MinKNOW’s defaults it looks like:
| Platform | Path shape |
|---|---|
| Linux | /data/<experiment>/<sample>/<timestamp_devid>/ |
| macOS | /Library/MinKNOW/data/<experiment>/<sample>/<timestamp_devid>/ |
| Windows | C:\data\<experiment>\<sample>\<timestamp_devid>\ |
Not the parent, and not fastq_pass/ itself. The directory must already exist
and must resolve under the configured output root — see why a directory gets
rejected. The path is
read by the daemon, so it must be valid on the daemon’s host, which is not
necessarily the machine your browser is on.
Map barcodes to samples
Under Barcode → sample mapping, type a barcode name and press Enter or click Add barcode; then pick the sample from the dropdown, which lists this sequencing order’s samples by alias. Remove deletes a row. Add one row for every barcode you expect.
Names are lower-cased as you add them, so BARCODE01 and barcode01 are the
same row. What you type has to match the folder name MinKNOW will create:
| Your run | What to map |
|---|---|
| Standard barcoding | barcode01, barcode02, … — one row each |
| Reads MinKNOW cannot assign | unclassified, if you want them linked anywhere |
| Sample-alias folders instead of barcode folders | the alias, exactly as the folder is named |
| A non-barcoded run | the single key no_barcode |
Files that land in a folder you did not map are still recorded — they appear in By barcode as unmapped and in the event log — but they are not linked to a sample and their reads and bases are never counted.
Start receiving
Start receiving creates the stream. The daemon picks it up on its next tick,
attaches a watcher to <run folder>/fastq_pass, and immediately scans whatever
is already there, so files MinKNOW wrote before you pressed the button are not
lost.
The barcode map is fixed once the stream is receiving. The interface says so plainly, and the reason is the audit trail: a mapping that changed mid-run would make the event log ambiguous. To correct a mapping, stop the stream and start a new one on the same directory. Files already ingested keep their old link; files that arrive afterwards use the new map, and the new stream re-scans the folder from the beginning, so previously unmapped files are picked up under the corrected mapping.
Watching it run
While the selected stream is live the page polls three endpoints on separate timers: the event feed every 3 seconds, the per-barcode aggregates every 5 seconds, and the run list and daemon status every 5 seconds. A stopped run is fetched once instead — its figures cannot change again — so reading history costs one request per panel, not a poll.
The header card shows the watched Output directory, Elapsed since start, total Reads and Bases across every barcode, and Monitor heartbeat — the last time the daemon touched this run. A heartbeat drifting past your poll interval means the monitor process has probably died. On a stopped run Elapsed becomes Duration — start to stop, not counting up — and the heartbeat line is replaced by when the run stopped.
Barcode mapping restates the mapping this stream was started with, resolved to sample names.
By barcode is the useful one during a run — server-side aggregates over the whole run, one row per barcode: reads, bases, average read length, a reads/second rate derived from the change since the previous poll (blank on the first poll), file count, and how long ago the last file arrived, with a pulsing dot while the barcode is still producing. Rows marked unmapped arrived in a folder that was not in the mapping. On a stopped run the same table shows final totals, without the rate column and without the pulsing dot, both of which need a second poll to mean anything.
Recent files is a collapsible list of the last 20 ingested files — when, barcode, sample, size and full path.
Audit trail is the raw event feed, newest first, capped at the 50 most recent
events the page has loaded. It is labelled debug-only, and it is where an
ERROR payload tells you why a specific file was skipped.
Run history
A sequencing order can hold more than one stream — a corrected barcode map, a restarted flow cell, a second run on the same order. As soon as there is more than one, a row of buttons appears at the top of the header card, one per run, newest first, up to the 50 the list endpoint returns. Each button carries a dot (pulsing green while the run is live, grey once it is stopped), the word Live or Stopped, and the run’s start time.
Click one to read it. Every panel below — the header figures, the barcode mapping, By barcode, Recent files and the Audit trail — follows the selection, so a finished run’s per-barcode totals, ingested files and events stay reachable for as long as the run row exists.
The page picks for you until you click: the live run if there is one, otherwise the most recent. Starting a new stream clears your selection and moves you to the run you just started. Stop receiving only ever appears on the run that is actually active, so selecting an old run cannot stop a live one by mistake.
Back on Sequencing Data → Overview, each streamed sample carries a Streaming badge with its file count, read count and bases, so you can see progress without leaving the sample table.
Stopping
Stop receiving is a soft stop. The app sets the run to STOPPING and records
the request; the daemon closes the watcher on its next tick and writes STOPPED.
Expect a delay of up to one poll interval. Pressing it twice is harmless — a run
that is already stopping or stopped answers success without changing anything.
Stopping detaches the watcher and nothing else. Every ingested file, every event
and the seeded Read rows stay on the sequencing order.
A stopped stream stays readable. When the run leaves ACTIVE the page
keeps it selected and switches it to its finished form — final totals,
duration, the barcode map it ran with, its ingested files and its whole event
trail — and the run history strip lets you come back to it
later. Nothing is captured at stop time and nothing needs to be: the panels
read the same stream
endpoints as they do
during a run, so a stopped run shows whatever is still in the database. The
strip lists the 50 most recent runs, which is what
GET /api/orders/{id}/stream returns; an order with more than that has older
runs reachable only through the API.
After the run
Because only the first chunk per sample became a Read, a streamed sequencing
order is not finished when the stream stops. Treat the stream as live
monitoring, and settle the sequencing data the normal way:
- Let MinKNOW finish and write its final files.
- Move or expose the run’s output under the configured data path — see Data Storage.
- Run Discover & Associate on the sequencing order and assign the complete read sets to samples.
Then launch pipelines. A pipeline started against the stream-seeded Read alone
analyses a single chunk of the run.
Doing it over the API
Everything above is four endpoints, all requiring a facility-admin session — read endpoints also accept a demo session, mutating ones do not:
| Endpoint | Purpose |
|---|---|
GET /api/orders/{id}/stream | The order’s runs, newest first, up to 50, each with its latest event |
POST /api/orders/{id}/stream | Start. outputDir required; optional barcodeMap, deviceId, flowCellId, minknowRunId |
GET /api/orders/{id}/stream/{streamRunId}/events | Cursor-paginated feed — ?after=<seq>, ?limit=<n> clamped to 1–500, default 100 |
GET /api/orders/{id}/stream/{streamRunId}/by-barcode | Per-barcode aggregates for the run |
POST /api/orders/{id}/stream/{streamRunId}/stop | Request a stop |
Request and response shapes, including the exact error bodies, are in Reference → App API.