open-nomad/website/content/api-docs/events.mdx

---
layout: api
page_title: Events - HTTP API
sidebar_title: Events
description: |-
  The /event endpoints are used to query for and stream Nomad events.
---

# Events HTTP API

The `/event/stream` endpoint is used to stream events generated by Nomad.

## Event Stream

This endpoint streams a servers backlog of events as well as new events as they occur.
The stream will be kept alive until the connection is closed.

| Method | Path               | Produces           |
| ------ | ------------------ | ------------------ |
| `GET`  | `/v1/event/stream` | `application/json` |

The table below shows this endpoint's [required ACLs](/api-docs#acls). Due to
the nature of this endpoint individual topics require specific policies.

Note that if you do not include a `topic` parameter all topics will be included
by default, requiring a management token.

| Topic        | ACL Required         |
| ------------ | -------------------- |
| `*`          | `management`         |
| `ACLToken`   | `management`         |
| `ACLPolicy`  | `management`         |
| `Job`        | `namespace:read-job` |
| `Allocation` | `namespace:read-job` |
| `Deployment` | `namespace:read-job` |
| `Evaluation` | `namespace:read-job` |
| `Node`       | `node:read`          |

### Parameters

- `index` `(int: 0)` - Specifies the index to start streaming events from. If
  the requested index is no longer in the buffer the stream will start at the
  next available index.

- `namespace` `(string: "default")` - Specifies the target namespace to filter
  on. Specifying `*` includes all namespaces for event types that support
  namespaces.

- `topic` `(topic:filter_key: "*:*")` - Specifies a topic to subscribe to and
  filter on. The default is to subscribe to all topics. Multiple topics may be
  specified by passing multiple `topic` parameters. A valid topic parameter
  includes a `topic` type and an optional `filter_key` separated by a colon
  `:`. As an example `?topic=Deployment:redis` would subscribe to all
  `Deployment` events for a job redis. an additional topic
  `&topic=Deployment:web` would include deployment events for redis and web. To
  only subscribe to `Node` events a topic parameter of `?topic=Node` without a
  separator value would be used. `?topic=Node:*` is also valid.

### Event Topics

| Topic      | Output                          |
| ---------- | ------------------------------- |
| ACLToken   | ACLToken                        |
| ACLPolicy  | ACLPolicy                       |
| Allocation | Allocation (no job information) |
| Job        | Job                             |
| Evaluation | Evaluation                      |
| Deployment | Deployment                      |
| Node       | Node                            |
| NodeDrain  | Node                            |

### Event Types

| Type                          |
| ----------------------------- |
| ACLTokenUpserted              |
| ACLTokenDeleted               |
| ACLPolicyUpserted             |
| ACLPolicyDeleted              |
| AllocationCreated             |
| AllocationUpdated             |
| AllocationUpdateDesiredStatus |
| DeploymentStatusUpdate        |
| DeploymentPromotion           |
| DeploymentAllocHealth         |
| EvaluationUpdated             |
| JobRegistered                 |
| JobDeregistered               |
| JobBatchDeregistered          |
| NodeRegistration              |
| NodeDeregistration            |
| NodeEligibility               |
| NodeDrain                     |
| NodeEvent                     |
| PlanResult                    |

### Sample Request

```shell-session
# Subscribe to all events and topics
$ curl -s -v -N http://127.0.0.1:4646/v1/event/stream
```

```shell-session
# Start at index 100 and subscribe to all Evaluation events
$ curl -s -v -N http://127.0.0.1:4646/v1/event/stream?index=100&topic=Evaluation
```

```shell-session
$ curl -G -s -v -N \
--data-urlencode "topic=Node:ccc4ce56-7f0a-4124-b8b1-a4015aa82c40" \
--data-urlencode "topic=Deployment" \
--data-urlencode "topic=Job:web" \
http://127.0.0.1:4646/v1/event/stream
```

### Sample Response

```json
{
  "Index": 7,
  "Events": [
    {
      "Topic": "Node",
      "Type": "NodeRegistration",
      "Key": "ccc4ce56-7f0a-4124-b8b1-a4015aa82c40",
      "Namespace": "",
      "FilterKeys": null,
      "Index": 7,
      "Payload": {
        "Node": {
          "ID": "ccc4ce56-7f0a-4124-b8b1-a4015aa82c40",
          "Datacenter": "dc1",
          "Name": "nomad-4",
          "HTTPAddr": "127.0.0.1:4646",
          "TLSEnabled": false,
          "Attributes": {
            "cpu.arch": "amd64",
            "cpu.frequency": "4200",
            "cpu.modelname": "Intel(R) Core(TM) i7-8650U CPU @ 1.90GHz",
            "cpu.numcores": "8",
            "cpu.totalcompute": "33600",
            "driver.docker": "1",
            "driver.docker.bridge_ip": "172.17.0.1",
            "driver.docker.os_type": "linux",
            "driver.docker.runtimes": "runc",
            "driver.docker.version": "19.03.13",
            "driver.mock": "true",
            "driver.mock_driver": "1",
            "driver.raw_exec": "1",
            "kernel.name": "linux",
            "kernel.version": "5.4.0-48-generic",
            "memory.totalbytes": "16525733888",
            "nomad.advertise.address": "127.0.0.1:4646",
            "nomad.revision": "8c88f29bff0849720e33b0cc73af87495358f3b8",
            "nomad.version": "0.13.0-dev",
            "os.name": "ubuntu",
            "os.signals": "SIGBUS,SIGFPE,SIGTRAP,SIGTTOU,SIGWINCH,SIGXFSZ,SIGHUP,SIGILL,SIGALRM,SIGCHLD,SIGSYS,SIGXCPU,SIGPROF,SIGQUIT,SIGTERM,SIGUSR2,SIGCONT,SIGIO,SIGSEGV,SIGTTIN,SIGIOT,SIGKILL,SIGPIPE,SIGABRT,SIGINT,SIGSTOP,SIGTSTP,SIGURG,SIGUSR1",
            "os.version": "20.04",
            "unique.cgroup.mountpoint": "/sys/fs/cgroup/systemd",
            "unique.hostname": "x1c",
            "unique.network.ip-address": "127.0.0.1",
            "unique.storage.bytesfree": "299488927744",
            "unique.storage.bytestotal": "502468108288",
            "unique.storage.volume": "/dev/nvme0n1p2"
          },
          "NodeResources": {
            "Cpu": {
              "CpuShares": 33600
            },
            "Memory": {
              "MemoryMB": 15760
            },
            "Disk": {
              "DiskMB": 285614
            },
            "Networks": [
              {
                "Mode": "bridge",
                "Device": "",
                "CIDR": "",
                "IP": "",
                "MBits": 0,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              },
              {
                "Mode": "host",
                "Device": "lo",
                "CIDR": "127.0.0.1/32",
                "IP": "127.0.0.1",
                "MBits": 1000,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              },
              {
                "Mode": "host",
                "Device": "lo",
                "CIDR": "::1/128",
                "IP": "::1",
                "MBits": 1000,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              }
            ],
            "NodeNetworks": [
              {
                "Mode": "bridge",
                "Device": "",
                "MacAddress": "",
                "Speed": 0,
                "Addresses": null
              },
              {
                "Mode": "host",
                "Device": "lo",
                "MacAddress": "",
                "Speed": 1000,
                "Addresses": [
                  {
                    "Family": "ipv4",
                    "Alias": "default",
                    "Address": "127.0.0.1",
                    "ReservedPorts": "",
                    "Gateway": ""
                  },
                  {
                    "Family": "ipv6",
                    "Alias": "default",
                    "Address": "::1",
                    "ReservedPorts": "",
                    "Gateway": ""
                  }
                ]
              }
            ],
            "Devices": null
          },
          "ReservedResources": {
            "Cpu": {
              "CpuShares": 0
            },
            "Memory": {
              "MemoryMB": 0
            },
            "Disk": {
              "DiskMB": 0
            },
            "Networks": {
              "ReservedHostPorts": ""
            }
          },
          "Resources": {
            "CPU": 33600,
            "MemoryMB": 15760,
            "DiskMB": 285614,
            "IOPS": 0,
            "Networks": [
              {
                "Mode": "host",
                "Device": "lo",
                "CIDR": "127.0.0.1/32",
                "IP": "127.0.0.1",
                "MBits": 1000,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              },
              {
                "Mode": "host",
                "Device": "lo",
                "CIDR": "::1/128",
                "IP": "::1",
                "MBits": 1000,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              }
            ],
            "Devices": null
          },
          "Reserved": {
            "CPU": 0,
            "MemoryMB": 0,
            "DiskMB": 0,
            "IOPS": 0,
            "Networks": null,
            "Devices": null
          },
          "Links": null,
          "Meta": {
            "connect.gateway_image": "envoyproxy/envoy:v1.11.2@sha256:a7769160c9c1a55bb8d07a3b71ce5d64f72b1f665f10d81aa1581bc3cf850d09",
            "connect.log_level": "info",
            "connect.sidecar_image": "envoyproxy/envoy:v1.11.2@sha256:a7769160c9c1a55bb8d07a3b71ce5d64f72b1f665f10d81aa1581bc3cf850d09"
          },
          "NodeClass": "",
          "ComputedClass": "v1:9803688035578634002",
          "Drain": false,
          "DrainStrategy": null,
          "SchedulingEligibility": "eligible",
          "Status": "initializing",
          "StatusDescription": "",
          "StatusUpdatedAt": 1602770857,
          "Events": [
            {
              "Message": "Node registered",
              "Subsystem": "Cluster",
              "Details": null,
              "Timestamp": "2020-10-15T10:07:37-04:00",
              "CreateIndex": 0
            }
          ],
          "Drivers": {
            "docker": {
              "Attributes": {
                "driver.docker": "true",
                "driver.docker.bridge_ip": "172.17.0.1",
                "driver.docker.os_type": "linux",
                "driver.docker.runtimes": "runc",
                "driver.docker.version": "19.03.13"
              },
              "Detected": true,
              "Healthy": true,
              "HealthDescription": "Healthy",
              "UpdateTime": "2020-10-15T10:07:37.904159516-04:00"
            },
            "exec": {
              "Attributes": null,
              "Detected": false,
              "Healthy": false,
              "HealthDescription": "Driver must run as root",
              "UpdateTime": "2020-10-15T10:07:37.445083368-04:00"
            },
            "java": {
              "Attributes": null,
              "Detected": false,
              "Healthy": false,
              "HealthDescription": "Driver must run as root",
              "UpdateTime": "2020-10-15T10:07:37.445601605-04:00"
            },
            "mock_driver": {
              "Attributes": {
                "driver.mock": "true"
              },
              "Detected": true,
              "Healthy": true,
              "HealthDescription": "Healthy",
              "UpdateTime": "2020-10-15T10:07:37.445193068-04:00"
            },
            "qemu": {
              "Attributes": null,
              "Detected": false,
              "Healthy": false,
              "HealthDescription": "",
              "UpdateTime": "2020-10-15T10:07:37.445684857-04:00"
            },
            "raw_exec": {
              "Attributes": {
                "driver.raw_exec": "true"
              },
              "Detected": true,
              "Healthy": true,
              "HealthDescription": "Healthy",
              "UpdateTime": "2020-10-15T10:07:37.445431163-04:00"
            }
          },
          "CSIControllerPlugins": null,
          "CSINodePlugins": null,
          "HostVolumes": null,
          "CreateIndex": 7,
          "ModifyIndex": 7
        }
      }
    }
  ]
}
```