> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drkm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs and workloads

> Give work a durable identity from submission through accepted results.

## What a job is

A job is a finite operation over records, or a continuous stream, with an identity that outlives the request, conversation or sandbox that submitted it. The platform seals inputs and code at admission, cuts records into partitions, places attempts on eligible outposts, retries under the operation’s declared replay policy, accepts exactly one output per partition and settles the job with explicit coverage. Finite work and streams alike survive an outpost restart.

| Kind | What it runs |
| - | - |
| **script** | Your Python entrypoint, called once as `run(records, context)` with every record. |
| **sweep** | A Broom pipeline: rows read where the data is, with detectors and your own per-row Python over them, placed stage by stage. |
| **predict** | A served detector over every record’s image, with no code and no sandbox. |
| **task** | A prompt for an agent, here or on a peer. It can pause with a question. |
| **overwatch\_scan** | An Overwatch area scan (*Scan* in the console); the outpost plans one record per tile. |
| **stream** | Continuous work opened by a feed, such as a Watchdog guard. It runs until stopped. |

## Follow the lifecycle

States are `queued`, `running`, `input_required` and the four terminal states `completed`, `partial`, `failed` and `canceled`; the console shows canceled as *Stopped*. Coverage counts partitions: expected, completed, failed, running, pending. A job completes when every partition is accepted, settles partial when some are, and fails when none are. A partial result keeps its coverage and is never a complete dataset with holes.

Read its current state, wait for settlement and retrieve accepted rows from any later run with the job ID.

```python Inspect an existing job theme={null}
import drkm

drkm.connect()
job = drkm.Job("your-job-id")

print(drkm.job(job.id)["coverage"])
job.wait()
print(job.rows())
```

## Make retries intentional

Silence is not failure. An attempt that times out is recorded as unknown and one that is stopped as canceled; both are silence. A replay-safe operation’s partition returns to the queue for another attempt while attempts remain. A script declared `replay_safe=False` fails instead of running twice, and since a script is one partition, its job fails. Silence counts against `max_attempts`; a receiver’s busy refusal does not. The attempt timeout restarts when the receiver reports work in progress, and an attempt still queued at a receiver may wait up to four timeout windows for a slot before it is recorded as unknown.

A submission `key` is scoped to you: the same key with the same sealed work replays the existing job, the same key with different work is refused with a conflict, and renaming a retry still replays because the name is outside the fingerprint.

```bash Terminal theme={null}
drkm console jobs --limit 50
drkm console jobs YOUR_JOB_ID
drkm console jobs YOUR_JOB_ID --runs | less      # every partition and attempt
```

> [!NOTE]
>
> In the console, the Jobs tab of the Outposts page groups work as Running, Needs an answer and Finished, with filters by author and kind and a search by name or ID. A job’s page shows where its partitions ran, why work moved, the errors behind its failed partitions grouped by message, and the download of a settled result.

## Streams and schedules

A stream takes no input records and has no finite result: a Watchdog guard is one durable continuous job per feed. Closing the browser does not stop it, an outpost that restarts or loses power resumes it under the same job ID, and feed interruptions are retried while it runs. An explicit **Stop** ends it; so does a failure of the guard itself, which settles it as failed.

A schedule runs an action on a cron or at one time: an agent prompt, admitted as a task job; a bash or Python script, admitted as a script job with one attempt and never replayed; or a wake that prompts the agent in a chat. An occurrence’s job is admitted with the occurrence as its idempotency key, and while an earlier occurrence’s job or wake is still active, the next one is skipped rather than queued behind it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.