open-nomad/website/content/docs/commands/job/dispatch.mdx

---
layout: docs
page_title: 'Commands: job dispatch'
description: |
  The dispatch command is used to create an instance of a parameterized job.
---

# Command: job dispatch

The `job dispatch` command is used to create new instances of a [parameterized
job]. The parameterized job captures a job's configuration and runtime
requirements in a generic way and `dispatch` is used to provide the input for
the job to run against. A parameterized job is similar to a function definition,
and dispatch is used to invoke the function.

Each time a job is dispatched, a unique job ID is generated. This allows a
caller to track the status of the job, much like a future or promise in some
programming languages.

## Usage

```plaintext
nomad job dispatch [options] <parameterized job> [input source]
```

Dispatch creates an instance of a parameterized job. A data payload to the
dispatched instance can be provided via stdin by using "-" for the input source
or by specifying a path to a file. Metadata can be supplied by using the meta
flag one or more times.

The payload has a **size limit of 16384 bytes (16KiB)**.

An optional idempotency token can be specified to prevent dispatching more than
one instance of the same job. The token can have any value and will be matched
with existing jobs. If an instance with the same token already exists, the job
will not be dispatched.

Upon successful creation, the dispatched job ID will be printed and the
triggered evaluation will be monitored. This can be disabled by supplying the
detach flag.

On successful job submission and scheduling, exit code 0 will be returned. If
there are job placement issues encountered (unsatisfiable constraints, resource
exhaustion, etc), then the exit code will be 2. Any other errors, including
client connection issues or internal errors, are indicated by exit code 1.

When ACLs are enabled, this command requires a token with the `dispatch-job`
capability for the job's namespace. The `list-jobs` capability is required to
run the command with a job prefix instead of the exact job ID. The `read-job`
capability is required to monitor the resulting evaluation when `-detach` is
not used.

See the [multiregion] documentation for additional considerations when
dispatching parameterized jobs.

## General Options

@include 'general_options.mdx'

## Dispatch Options

- `-meta`: Meta takes a key/value pair separated by "=". The metadata key will
  be merged into the job's metadata. The job may define a default value for the
  key which is overridden when dispatching. The flag can be provided more than
  once to inject multiple metadata key/value pairs. Arbitrary keys are not
  allowed. The parameterized job must allow the key to be merged.

- `-detach`: Return immediately instead of monitoring. A new evaluation ID
  will be output, which can be used to examine the evaluation using the
  [eval status] command

- `-idempotency-token`: Optional identifier used to prevent more than one
  instance of the job from being dispatched.


- `-id-prefix-template`: Optional prefix template for dispatched job IDs.

- `-verbose`: Show full information.

## Examples

Dispatch against a parameterized job with the ID "video-encode" and
passing in a configuration payload via stdin:

```shell-session
$ cat << EOF | nomad job dispatch video-encode -
{
  "s3-input": "https://video-bucket.s3-us-west-1.amazonaws.com/cb31dabb1",
  "s3-output": "https://video-bucket.s3-us-west-1.amazonaws.com/a149adbe3",
  "input-codec": "mp4",
  "output-codec": "webm",
  "quality": "1080p"
}
EOF
Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
Evaluation ID     = 31199841

==> Monitoring evaluation "31199841"
    Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
    Allocation "8254b85f" created: node "82ff9c50", group "cache"
    Evaluation status changed: "pending" -> "complete"
==> Evaluation "31199841" finished with status "complete"
```

Dispatch against a parameterized job with the ID "video-encode" and
passing in a configuration payload via a file:

```shell-session
$ nomad job dispatch video-encode video-config.json
Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
Evaluation ID     = 31199841

==> Monitoring evaluation "31199841"
    Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
    Allocation "8254b85f" created: node "82ff9c50", group "cache"
    Evaluation status changed: "pending" -> "complete"
==> Evaluation "31199841" finished with status "complete"
```

Dispatch against a parameterized job with the ID "video-encode" using the detach
flag:

```shell-session
$ nomad job dispatch -detach video-encode video-config.json
Dispatched Job ID = example/dispatch-1485380684-c37b3dba
Evaluation ID     = d9034c4e
```

Dispatch with an idempotency token for the first time:

```shell-session
$ nomad job dispatch -idempotency-token=prod video-encode video-config.json
Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
Evaluation ID     = 31199841

==> Monitoring evaluation "31199841"
    Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
    Allocation "8254b85f" created: node "82ff9c50", group "cache"
    Evaluation status changed: "pending" -> "complete"
==> Evaluation "31199841" finished with status "complete"
```

Dispatch with the same idempotency token:

```shell-session
$ nomad job dispatch -idempotency-token=prod video-encode video-config.json
Job "video-encode/dispatch-1485379325-cb38d00d" already dispatched with idempotency token "prod".
```

Dispatch with an id prefix:

```shell-session
$ nomad job dispatch -id-prefix-template=config1 video-encode video-config1.json
Jb
Dispatched Job ID = video-encode/dispatch-config1-1485379325-cb38d00d
Evaluation ID     = 31199841

==> Monitoring evaluation "31199841"
    Evaluation triggered by job "example/dispatch-config1-1485379325-cb38d00d"
    Allocation "8254b85f" created: node "82ff9c50", group "cache"
    Evaluation status changed: "pending" -> "complete"
==> Evaluation "31199841" finished with status "complete"
```

[eval status]: /nomad/docs/commands/eval/status
[parameterized job]: /nomad/docs/job-specification/parameterized 'Nomad parameterized Job Specification'
[multiregion]: /nomad/docs/job-specification/multiregion#parameterized-dispatch