Jobs and Moving Data

🇬🇧 English · 🇫🇷 Français

Jobs, Bulk Actions and Moving Data

Applies to Hydranos 4.4.

This page is for anyone who acts on many torrents at once, moves data between folders or disks, or deletes torrents. You will learn what every context-menu item really does, how a data move runs and fails, what the Jobs tab shows, and exactly which files a removal deletes.

Two words are used strictly here. A bulk task is what a context-menu action starts: it lives in memory and has a progress panel. A job is a persistent background move (move_data, graduate, or handoff for a move to another node) listed on the Jobs tab. Other terms (store, resume state, seed mode) are defined on Concepts and Glossary.

Bulk actions

Select rows in the Race or Hoard list, then right-click. Click selects one row, Ctrl/Cmd-click toggles one, Shift-click selects a range. Ctrl+A on the Hoard table selects every torrent the current filter matches, not only the 500 rows drawn. Ctrl+A does nothing on the Race table.

Every menu item except the Export group sends the selection to POST /api/selection/<action> and starts one bulk task (Export downloads a file, see Exporting). The selection travels in one of two forms:

• By rows: the hashes you picked, each with its copy (local-hoard, local-race, or <node>-<engine> for a remote row).
• By filter (Ctrl+A): the list filter itself, plus expect, the count you were shown. If the filter now matches more torrents than expect, the server refuses with 409 grew and the UI asks The filter now matches {n} torrents, not {m}. Apply to all {n}?. Fewer is accepted. An empty selection is always refused; it never means "everything".

Above 500 torrents, Stop, Start and both Remove items ask for confirmation first. Cancel on the progress panel stops between two torrents for per-torrent actions, between batches of 10,000 torrents for Stop, Start, Force download, Edit tags, Share limits… and Change category › (store-only edits), and between rounds of 8 for Reannounce. The panel and its outcome lines are described on Web UI Tour. A bulk task is lost at restart and never appears on the Jobs tab.

Menu item	What it does	Hoard rows	Race rows
Stop / Start	Writes your stop/start intent in the store (it survives restarts), then stops or starts the copy in its engine	yes	yes
Force download / Stop forcing	Marks an incomplete torrent as forced (filter Forced): the download queue runs it past its ceiling, see Queue, Share and Speed Limits	yes	skipped
Reannounce	Asks the announce scheduler to announce now; outcomes ok, in_flight, cooldown, queued	yes	yes
Recheck	Hash-checks the copy the row names, in its own engine; guarded when another torrent names the same files (see Files another torrent already holds). Menu item shown when a hoard row is selected, or after Ctrl+A	yes	yes
Change category ›	Label only, No category clears it. No file moves, no engine change	yes	yes
Change category + move files ›	The data follows the category's save path, as a job; a category of the other mode is a graduation	yes	yes
Set location…	Moves the data to a folder you type; the category does not change	yes	yes
Limit rate…	The copy's own upload/download cap (see Queue, Share and Speed Limits)	yes	yes
Share limits…	The torrent's ratio and seeding-time limits (same page)	yes	yes
Sequential download, First/last piece first	Download order of the copy (see Download order)	yes	yes
Edit tags ›	Adds or removes one tag (menu item shown when a hoard row is selected, or after Ctrl+A)	yes	skipped
Duplicate to engine ›	Seeds the same files from a second engine (see Copies in several engines)	yes	yes
Move to engine ›	Hands the torrent to another engine with its state; the files do not move	yes	yes
Download .torrent files (.zip), Download hash list (.txt), Download as CSV	Export (see Exporting)	yes	yes
Remove torrent / Remove + delete files	Removes the selected copy only (see Deleting)	yes	yes

"Skipped" rows are counted as {n} not applicable in the progress panel. Every per-copy item acts on the copy the row is: an extra engine's row (local-<id>) sends ?engine=<id> (or ?agent=local-<id>). Reannounce and Duplicate to engine › are the exceptions: Reannounce announces the first copy found (below), Duplicate points the new engine at the first copy's save path. Rows that come from another node are relayed to that node (Stop/Start, Reannounce, Recheck, both Change category items, Set location…, Limit rate…, download order, Remove); Edit tags ›, Force download and Share limits… are counted {n} not on this node. On remote rows the engine items offer only local-<id> (bring it here, a fetch) and, under Move to engine ›, the other engines of the node that holds the row (there, no copy). See Nodes and Multiple Machines.

Known bug in 4.4: a bulk Reannounce looks like it acts on the copy the row is, like Stop, Recheck or Limit rate… — it names no engine, so for a hash held by two engines it announces the first copy found, which may be the other one. Found by reading the code, not reproduced — to announce one copy, call POST /api/torrents/<hash>/reannounce?engine=<id>.

Recheck and Edit tags › are hidden when the selection holds no hoard row, and Ctrl+A does not exist on the Race table: from the Race tab alone there is no bulk recheck in the menu. Use the API instead (POST /api/selection/recheck, below), which rechecks race copies too.

The same thing over the API

# Stop every torrent of category "tv" in the hoard list (expect = the count you saw)
curl -X POST http://localhost:8199/api/selection/stop \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"selection":{"filter":"category=tv","view":"hoard","expect":120},"params":{}}'
# -> 202 {"job":"sel…","total":120}

curl -H "X-Api-Key: YOUR_API_KEY" http://localhost:8199/api/selection/jobs/sel0123456789ab

Filter keys: search, category, category_not, tag, tag_not, tracker, tracker_not, error_class, error_class_not, state. Every body rejects unknown fields with a 400 that names them. The full action list is on REST API.

Moving data

Six things start a data move inside Hydranos:

• Set location…: any absolute folder, category unchanged.
• Change category + move files ›: the category's Save Path. The decision tree (relabel, move, or graduate to the other engine) is drawn on Categories and Routing.
• A workflow action move files to a folder (set_location): same checks as Set location… (see Workflows).
• The MCP tool move_to_category, which sends the same request as Change category + move files › (see MCP Server).
• POST /api/torrents/:hash/graduate {"engine":"hoard","category":"tv"} (or a save_path; without one the category's Save Path is used, else 400 save_path is required (or a category that has one)). It runs the same checks as a category move below, takes "allow_breaking_hardlinks": true, and answers 200 {"status":"queued","job":…,"plan":…}.
• The race drain, which queues graduate jobs without these checks (see Race Drain, Graduation and Seed Obligations).

A move to another node is not a data move on this machine: it is a handoff job that waits for the node (see The Jobs tab).

Set location

The prompt reads Absolute path of the folder to move the data to. The category does not change. A torrent with several files keeps its own folder inside this one. With one row selected it is prefilled with the current save path.

• The path must be absolute and .. is refused (400); a . inside the path is silently dropped (/data/./tv becomes /data/tv). A trailing separator is dropped. The API does not trim spaces (folder names can end with one); the UI trims what you type. Drive paths (D:\media) are accepted on the Windows build only; on Linux they are refused as not absolute.
• A multi-file torrent lands in <target>/<torrent name>/…; a single-file torrent lands directly in <target>.
• Only the torrent's own files move, file by file. Other files in the same folder stay. Files missing at the source are skipped.
• If the target folder is the torrent's current save path (a path comparison, not a look at the files), nothing is queued: 200 {"status":"ok","moved":false}.

curl -X POST http://localhost:8199/api/hoard/torrents/0123456789abcdef0123456789abcdef01234567/location \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"location":"/data/archive"}'
# -> 202 {"status":"moving","job":"job…","kind":"move_data","plan":{…}}

Use /api/race/… for a race copy, and ?engine=vpn1 for a copy in an extra engine.

Checks before a move is queued

flowchart TD
    A["Set location, Change category + move files,<br/>workflow set_location"] --> K{"Category change to a category<br/>of the other mode?"}
    K -->|"no, or Set location"| N{"Target folder = current<br/>save path?"}
    N -->|"yes"| N2["200, moved false<br/>nothing queued"]
    N -->|"no"| B
    K -->|"yes, even if the save path<br/>does not change"| B{"unsafe_path, shared<br/>or destination_taken?"}
    G["POST /api/torrents/HASH/graduate"] --> B
    B -->|"yes"| X["409, refused<br/>whatever you answer"]
    B -->|"no"| C{"Hardlinked files need a copy<br/>and no consent given?"}
    C -->|"yes"| H["409 hardlinks<br/>UI asks: Move them anyway?"]
    H -->|"yes: resent with allow_breaking_hardlinks"| A
    C -->|"no"| D{"Enough free space<br/>at the target?"}
    D -->|"no"| S["409 space"]
    D -->|"yes"| Q{"A move already queued<br/>or running for this torrent?"}
    Q -->|"yes"| Q2["409 already queued"]
    Q -->|"no, same mode"| MD["202: move_data job<br/>same engine, checks run again,<br/>rollback on failure"]
    Q -->|"no, other mode, or /graduate"| GR["graduate job queued<br/>202, or 200 from /graduate"]
    DR["Race drain"] -->|"no path, shared, destination,<br/>hardlink or space check;<br/>skipped if a move is already queued"| GJ
    GR --> GJ["graduate job runs:<br/>removed from source first,<br/>rolled back on failure or Cancel"]

Loading

For Change category + move files › the mode test comes first: a category of the other mode always queues a graduate, even when its save path is the one the data is already in.

Refusal	HTTP	Meaning	Can you override it?
bad path	400	not absolute, or contains ..	no
unsafe_path	409	the .torrent names a file outside its own folder	no
shared	409	another loaded torrent, in any engine, reads one of the same file paths (a cross-seed, for example), this torrent's own copy in another engine included (after Duplicate to engine ›); moving would leave it serving nothing	no
destination_taken	409	a file already exists at the destination and is not the same file (another torrent's file of the same name, typically): N file(s) already exist at the destination (…); moving onto them would overwrite them. See Files another torrent already holds	no
hardlinks	409	a file that must be copied (target on another filesystem) has another name on disk, usually in your Sonarr/Radarr library; the copy would break the link and double the space. In Docker the usual cause is two separate bind mounts, which you can fix: see One parent mount, for hardlinks on Install with Docker	yes: "allow_breaking_hardlinks": true. The UI asks once per selection; if you say no, those torrents count as left in place (hardlinks)
space	409	free space at the target is smaller than the bytes to copy (renames cost nothing)	no
already queued	409	one pending move per torrent, either kind	wait for the job

Every 409 except "already queued" carries a plan object: from, to, files, bytes, missing_files, rename_files, copy_files, copy_bytes, hardlinked_files, hardlinked_bytes, free_bytes, enough_space, unsafe_path, shared_with, occupied (the files already at the destination), and a reason naming the row of the table above. "The same file" means the same inode on Linux (a hardlink of it is fine) and the same canonical path on Windows.

A move_data job runs these checks (unsafe_path, shared, destination_taken, hardlinks, space) again when its turn comes, and fails with …; nothing was moved if one no longer passes. A graduate job does not re-run them: it only refuses, per file, a hardlinked file to copy without consent or a file larger than the free space, and rolls back.

Dry run. GET /api/{race,hoard}/torrents/:hash/move-preview?category=tv answers kind (relabel, move_data or graduate), engine, target_engine and, for move_data and graduate, the same plan (a relabel answer has none), without moving anything. category is required (400 without it). It previews a category move only; there is no preview for a free-form location.

Jobs

A job is a row in the store's jobs table. It survives restarts. Two kinds move data on this machine:

	move_data	graduate
Started by	Set location…, Change category + move files › (same mode), workflow set_location	Change category + move files › to a category of the other mode, the race drain, POST /api/torrents/:hash/graduate
Engine	stays the same	moves to the other engine
Seeding during the copy	yes, from the originals	no: the torrent leaves the source engine before any file moves
How files move	same filesystem: rename; other filesystem: copy all first, delete originals at the end	per file: rename, or copy then delete the source right away
The torrent afterwards	its own resume record re-imported at the new folder, as it was (see After a move)	adopted with its own resume record, as it was
On failure	rolled back	rolled back: files moved back, torrent back in its source engine as it was
Cancel while running	refused (409): it finishes	stops after the current file, then rolled back

A third kind, handoff, moves nothing here: it is a move to another node waiting for that node to hold a full copy (see The Jobs tab).

Common rules:

• One job at a time for the whole instance, oldest first. The runner checks for work every 5 s. A handoff job does not take that slot.
• Copies are a plain read/write loop with 4 MiB buffers and an fsync per file. It deliberately avoids copy_file_range, so ZFS never block-clones the data. There is no speed cap and no config key for one.
• "Same filesystem" means same device id on Linux and same volume serial on Windows.
• After a restart, jobs that were running or cancelling go back to queued with progress reset, and run again from the start. They are not resumed where they stopped, and a cancel that had not finished is forgotten: cancel the job again. waiting (handoff) jobs keep waiting.
• Progress counts bytes of files copied or renamed.

What a move_data job does

sequenceDiagram
    participant U as You
    participant A as Hydranos API
    participant R as Jobs runner
    participant E as Engine
    participant D as Disk
    participant S as Store
    U->>A: POST .../location or .../category with move_files
    A->>A: checks (unsafe path, shared, destination taken, hardlinks, space, already queued)
    A-->>U: 202 + job id
    Note over R: one job at a time
    R->>R: re-plan and re-check shared, destination taken, hardlinks, free space
    R->>D: copy files whose target is on another filesystem
    Note over E,D: the torrent keeps seeding from the originals
    alt a copy fails
        R->>D: delete the copies made so far
        R->>S: job failed, nothing moved
    else copies done
        R->>E: take its resume record, remove the torrent, data kept
        R->>D: rename same-filesystem files
        R->>E: re-import the record at the new folder
        alt rename or re-import fails
            R->>D: undo renames, delete copies
            R->>E: re-import the record at the old folder
            R->>S: job failed, rolled back
        else re-imported
            R->>S: save path (and category) updated
            R->>D: delete the copied originals, prune emptied subfolders
            R->>S: job done
        end
    end

Loading

There is no hash-verify step: the copy is trusted. Emptied subfolders under the old save path are removed, never the old save path itself (other torrents may share it). If an original cannot be deleted at the end, the job still succeeds and the log warns.

What a graduate job does

1. Captures the torrent's resume record (pieces held, edited trackers, byte counters, seeding time, stopped state, its own rate caps and download order), then removes it from the source engine, keeping its data.
2. Moves each file: rename on the same filesystem; otherwise checks free space and hardlinks for that file, copies it, then deletes the source file. A Cancel is honoured between two files.
3. The target engine adopts the torrent at the new folder from that record, the way a restart reads it back: no recheck, nothing reset, a stopped torrent stays stopped.
4. Updates the store: engine, save path, category.

Any failure after step 1 (a hardlinked file without consent, a full disk, a target that refuses the torrent) and a Cancel are undone: the files already moved are moved back, the source engine adopts the record again, and the job ends with the reason followed by one of:

End of the message	State
rolled back, the torrent is in <engine> as before	back where it was
back in <engine>, but these files did not move back: …	back in its engine; the listed files are still at the destination, move them back by hand
ROLLBACK FAILED, re-add it by hand at <folder>: …	in no engine; its data is on disk. Re-add the .torrent (from Download .torrent files (.zip) or a backup) at that folder

A cancelled graduation ends as Cancelled, a failed one as Failed.

A graduation plans its files like a move first: if a file of the same name already sits at the destination (another torrent's, typically), the job is refused (… already exist …; nothing was moved) and the torrent stays where it is. The race drain checks the same before it queues a graduation, and logs the torrents it leaves in place for that reason, by category, as a WARN not graduated: files of the same name already sit at the destination….

After a move: what changes

Every move carries the torrent as it was. A graduation and Move to engine › hand its resume record to the target engine; a move_data job (Set location…, a same-mode Change category + move files ›, workflow set_location) re-imports the torrent's own record at the new folder. Pieces held, edited trackers, byte counters (so the ratio), seeding time, the stopped state, its own rate caps and download order are kept, with category, tags and share limits; nothing is rechecked, and an unfinished torrent goes on downloading at the new place.

Duplicate to engine › adds a second copy in seed mode, on the same files. It is refused (409 … does not hold all of it yet; duplicate it once it is complete) while the source is not complete or is being checked.

Your tracker's credit, for every kind of move: the source engine lets the torrent go without announcing stopped (a deletion does announce it), so upload made since its last announce is never reported. The moved torrent then starts a new announce session from 0, as after a restart (see Trackers and Announces). Upload already announced is credited by the tracker and stays.

The Jobs tab

The Jobs tab says Long-running work: moving a torrent's data between filesystems keeps running here, and the torrent keeps seeding while it does. That sentence is true for move_data only: a graduate job stops seeding while it copies, and a handoff job copies nothing here. It lists the 200 most recent jobs, refreshed every 2 s while the tab is open, plus a Refresh button. Active only keeps the jobs not yet finished (queued, running, cancelling, waiting).

Column	Content
State	Running, Waiting for the node (handoff), Done, Failed, Cancelled; a job waiting its turn shows the raw word queued, one being cancelled the raw word cancelling
Type	move_data, graduate or handoff
Torrent	name recorded when the job was queued, and the hash
Progress	bar with bytes done / total (for handoff, the node's progress); a failed job shows its error text here instead
Destination	target folder; for handoff, <node>-<engine> (or <node>)
Started	when the job was queued
(button)	Cancel, on queued, running and waiting jobs

With no rows, the table says Nothing running. Finished jobs stay in the list.

Cancel asks Cancel this job? A waiting job is dropped. A move to another engine stops after the current file and is put back as it was; another running move cannot be interrupted and finishes. A move to a node stops waiting: both copies are kept. What the server does:

Job	Answer	Effect
queued (any kind)	200 {"status":"cancelled"}	dropped before it starts; state Cancelled
graduate, running	200 {"status":"cancelling"}	stops after the current file and rolls back (see What a graduate job does); then Cancelled
move_data, running	409 a running move cannot be interrupted safely; it will finish	none: the job runs to the end (the UI shows the message)
handoff, waiting	200 {"status":"cancelled"}	stops waiting: the local copy is kept, the node keeps the one it received
finished	409 the job is already <state>	none
unknown id	404 no such job <id>	none

Moves to a node (handoff)

Move to engine › with a node target (<node>-<engine>) sends the torrent to the node, then queues a handoff job in state waiting (the bulk task counts it {n} sent; the local copy goes once the node holds it (Jobs)). Every 30 s the job asks the node how much it holds. At 100 % it removes every local copy with its files (except files a torrent of another hash reads). If the node is removed, or does not report a full copy within 6 hours (the deadline is stored in the job, so a restart keeps it), the job fails and the local copy is kept. A second move of the same torrent while one waits is refused (409 a move of this torrent to a node is already waiting; see Jobs). Duplicate to engine › to a node creates no job. Details: Nodes and Multiple Machines.

API: GET /api/jobs?limit= (default 100, newest first) and GET /api/jobs/:id, each job with id, type, state (queued, running, cancelling, waiting, done, failed, cancelled), info_hash, params, progress_bytes, total_bytes, percent, error, created_at, updated_at. DELETE /api/jobs/:id is Cancel, with the answers above. POST /api/jobs/move-remote is gone: any request gets 410 pointing to POST /api/selection/handoff (see Upgrading from 3.x).

Copies in several engines

One torrent can be held by more than one engine of the same instance. Each copy has its own category, stop state and peer id, and the copies share the same files.

	Duplicate to engine › → local-<id> (same files, second identity)	Move to engine › → local-<id> (here, no copy)
Route	POST /api/torrents/:hash/copy {"engine":"vpn1"}	POST /api/torrents/:hash/engine?engine=<source> {"engine":"vpn1"}
Copies afterwards	two: the source keeps seeding	one: the source lets go
Which copy is read	the first copy found (?engine= ignored)	the one ?engine= names (the menu sends the row's)
The new copy	added from the stored .torrent at the same save path, in seed mode, started: complete because the source is, the .torrent's trackers, counters at 0	adopted with the source's resume record: pieces, trackers, counters, seeding time, stopped state
Order	add to the target	the target adopts first, then the source lets go; if the target refuses, 500 the target engine refused it; nothing was changed; if the source then refuses to let go, the target copy is undone
Files	nothing is copied or moved on disk	nothing is copied or moved on disk
Refused	409 <engine> already seeds it; 409 … does not hold all of it yet; duplicate it once it is complete while the source is incomplete or being checked	400 already in <engine>, no engine named <engine> on this node

• Two copies on the same files are linked from then on: Set location… or a category move of either is refused with shared (moving would leave the other serving nothing), and Remove + delete files on one keeps the files the other reads (see Deleting).
• On most per-copy routes, ?engine=<id> picks which copy you mean (?agent=local-<id> is the legacy spelling of the same thing). /graduate and /copy ignore it and use the first copy found.
• Node targets (<node>-<engine>) are a handoff over BitTorrent: Move to engine › to a node is a handoff job (see Moves to a node), Duplicate to engine › to a node is not a job. See Nodes and Multiple Machines.

The Node menu group that holds these two items shows as soon as this instance has two engines (always, with the default race and hoard) or a node is declared. More on extra engines: Engines: Race and Hoard.

Exporting

The Export group downloads the selection (Ctrl+A included) as one streamed file:

Item	File	Content
Download .torrent files (.zip)	hydranos-<n>-torrents.zip	one <name> [<first 8 hash chars>].torrent per torrent, from the store; missing.txt lists hashes this instance does not hold
Download hash list (.txt)	hydranos-<n>-hashes.txt	one hash per line, no store lookup (remote rows included)
Download as CSV	hydranos-<n>-torrents.csv	header info_hash,name,size,category,tags,trackers,added_unix,save_path; unknown hashes still get a line holding only the hash (<hash>,,,,,,,)

For the zip, a dialog warns that a private tracker's .torrent carries your passkey in its announce URL and offers Keep trackers or Remove trackers. Remove trackers strips only announce and announce-list; the info hash is unchanged. A file that cannot be rewritten is left out and listed in missing.txt rather than exported with its passkey. The exported .torrent is the one stored at add time: tracker edits made in Hydranos are not in it.

curl -X POST "http://localhost:8199/api/torrents/export" -H "X-Api-Key: YOUR_API_KEY" \
  -d format=zip -d strip_trackers=1 \
  -d hashes=0123456789abcdef0123456789abcdef01234567 -o export.zip

The form takes selection (the same JSON as a bulk action) or hashes (comma-separated), and format=zip|txt|csv.

Deleting

Remove torrent keeps the files; Remove + delete files deletes them. From the context menu, each removes only the selected copy. The REST route DELETE /api/torrents/:hash?delete_files=true without engine removes every copy, as does the qBittorrent shim's torrents/delete.

What is deleted on disk:

• File by file, only the files the torrent names. Never a recursive folder delete. Emptied subfolders of a multi-file torrent are removed bottom-up; a folder that still holds a foreign file stays.
• Files another loaded torrent reads at the very same path are kept, in any engine: a cross-seed, an upload seeded from its source files, or this torrent's own copy in another engine pointed at the same folder (Duplicate to engine ›). The log says files kept: another torrent reads them. This compares paths, not inodes: a hardlink in your media library is another name and keeps its bytes anyway.
• A copy with a payload of its own protects nothing. If the race copy and the hoard copy of one torrent sit in two different folders (the same release grabbed twice), removing one with + delete files deletes its folder's files, whatever the other copy holds.
• Removing every copy at once (DELETE without engine) deletes each copy's own files, minus what a torrent of another hash reads; two copies on the same path lose that path once the last of them goes.
• A missing file is not an error.

For two torrents with different content under the same file names, see Files another torrent already holds: since 4.4 an add no longer lets them share a path (unless [dedup] path_collision = "legacy").

The engine sends stopped to the trackers, removes the torrent, then folds its lifetime bytes into the instance's all-time counters and drops the store row. The engine's resume state for that torrent is deleted. POST /api/race/torrents/:hash/purge removes the race copy the same way, with its files (minus files another copy or torrent reads), and leaves any hoard copy alone: see REST API. The MCP tool delete_torrents exists only when [mcp] allow_destructive = true (see MCP Server).

See also

• Categories and Routing: category modes, save paths and the category-move decision.
• Race Drain, Graduation and Seed Obligations: when the drain queues graduate jobs.
• Workflows: set_location and delete actions.
• Nodes and Multiple Machines: remote rows and handoff.
• Web UI Tour: selection, context menu and the progress panel.
• REST API: every route named on this page.