1---
2layout: api
3page_title: Agent - HTTP API
4description: |-
5  The /agent endpoints interact with the local Nomad agent to interact with
6  members and servers.
7---
8
9# Agent HTTP API
10
11The `/agent` endpoints are used to interact with the local Nomad agent.
12
13## List Members
14
15This endpoint queries the agent for the known peers in the gossip pool. This
16endpoint is only applicable to servers. Due to the nature of gossip, this is
17eventually consistent.
18
19| Method | Path             | Produces           |
20| ------ | ---------------- | ------------------ |
21| `GET`  | `/agent/members` | `application/json` |
22
23The table below shows this endpoint's support for
24[blocking queries](/api-docs#blocking-queries) and
25[required ACLs](/api-docs#acls).
26
27| Blocking Queries | ACL Required |
28| ---------------- | ------------ |
29| `NO`             | `node:read`  |
30
31### Sample Request
32
33```shell-session
34$ curl \
35    https://localhost:4646/v1/agent/members
36```
37
38### Sample Response
39
40```json
41{
42  "ServerName": "bacon-mac",
43  "ServerRegion": "global",
44  "ServerDC": "dc1",
45  "Members": [
46    {
47      "Name": "bacon-mac.global",
48      "Addr": "127.0.0.1",
49      "Port": 4648,
50      "Tags": {
51        "mvn": "1",
52        "build": "0.5.5dev",
53        "port": "4647",
54        "bootstrap": "1",
55        "role": "nomad",
56        "region": "global",
57        "dc": "dc1",
58        "vsn": "1"
59      },
60      "Status": "alive",
61      "ProtocolMin": 1,
62      "ProtocolMax": 5,
63      "ProtocolCur": 2,
64      "DelegateMin": 2,
65      "DelegateMax": 4,
66      "DelegateCur": 4
67    }
68  ]
69}
70```
71
72## List Servers
73
74This endpoint lists the known server nodes. The `servers` endpoint is used to
75query an agent in client mode for its list of known servers. Client nodes
76register themselves with these server addresses so that they may dequeue work.
77The servers endpoint can be used to keep this configuration up to date if there
78are changes in the cluster.
79
80| Method | Path             | Produces           |
81| ------ | ---------------- | ------------------ |
82| `GET`  | `/agent/servers` | `application/json` |
83
84The table below shows this endpoint's support for
85[blocking queries](/api-docs#blocking-queries) and
86[required ACLs](/api-docs#acls).
87
88| Blocking Queries | ACL Required |
89| ---------------- | ------------ |
90| `NO`             | `agent:read` |
91
92### Sample Request
93
94```shell-session
95$ curl \
96    https://localhost:4646/v1/agent/servers
97```
98
99### Sample Response
100
101```json
102["127.0.0.1:4647"]
103```
104
105## Update Servers
106
107This endpoint updates the list of known servers to the provided list. This
108**replaces** all previous server addresses with the new list.
109
110| Method | Path             | Produces       |
111| ------ | ---------------- | -------------- |
112| `POST` | `/agent/servers` | `(empty body)` |
113
114The table below shows this endpoint's support for
115[blocking queries](/api-docs#blocking-queries) and
116[required ACLs](/api-docs#acls).
117
118| Blocking Queries | ACL Required  |
119| ---------------- | ------------- |
120| `NO`             | `agent:write` |
121
122### Parameters
123
124- `address` `(string: <required>)` - Specifies the list of addresses in the
125  format `ip:port`. This is specified as a query string.
126
127### Sample Request
128
129```shell-session
130$ curl \
131    --request POST \
132    https://localhost:4646/v1/agent/servers?address=1.2.3.4:4647&address=5.6.7.8:4647
133```
134
135## Query Self
136
137This endpoint queries the state of the target agent (self).
138
139| Method | Path          | Produces           |
140| ------ | ------------- | ------------------ |
141| `GET`  | `/agent/self` | `application/json` |
142
143The table below shows this endpoint's support for
144[blocking queries](/api-docs#blocking-queries) and
145[required ACLs](/api-docs#acls).
146
147| Blocking Queries | ACL Required |
148| ---------------- | ------------ |
149| `NO`             | `agent:read` |
150
151### Sample Request
152
153```shell-session
154$ curl \
155    https://localhost:4646/v1/agent/self
156```
157
158### Sample Response
159
160```json
161{
162  "config": {
163    "Addresses": {
164      "HTTP": "127.0.0.1",
165      "RPC": "127.0.0.1",
166      "Serf": "127.0.0.1"
167    },
168    "AdvertiseAddrs": {
169      "HTTP": "127.0.0.1:4646",
170      "RPC": "127.0.0.1:4647",
171      "Serf": "127.0.0.1:4648"
172    },
173    "BindAddr": "127.0.0.1",
174    "Client": {
175      "AllocDir": "",
176      "ChrootEnv": {},
177      "ClientMaxPort": 14512,
178      "ClientMinPort": 14000,
179      "DisableRemoteExec": false,
180      "Enabled": true,
181      "GCDiskUsageThreshold": 99,
182      "GCInodeUsageThreshold": 99,
183      "GCInterval": 600000000000,
184      "MaxKillTimeout": "30s",
185      "Meta": {},
186      "NetworkInterface": "lo0",
187      "NetworkSpeed": 0,
188      "NodeClass": "",
189      "Options": {
190        "driver.docker.volumes": "true"
191      },
192      "Reserved": {
193        "CPU": 0,
194        "DiskMB": 0,
195        "MemoryMB": 0,
196        "ParsedReservedPorts": null,
197        "ReservedPorts": ""
198      },
199      "Servers": null,
200      "StateDir": ""
201    },
202    "Consul": {
203      "Addr": "",
204      "Auth": "",
205      "AutoAdvertise": true,
206      "CAFile": "",
207      "CertFile": "",
208      "ChecksUseAdvertise": false,
209      "ClientAutoJoin": true,
210      "ClientServiceName": "nomad-client",
211      "EnableSSL": false,
212      "KeyFile": "",
213      "ServerAutoJoin": true,
214      "ServerServiceName": "nomad",
215      "Timeout": 5000000000,
216      "Token": "",
217      "VerifySSL": false
218    },
219    "DataDir": "",
220    "Datacenter": "dc1",
221    "DevMode": true,
222    "DisableAnonymousSignature": true,
223    "DisableUpdateCheck": false,
224    "EnableDebug": true,
225    "EnableSyslog": false,
226    "Files": null,
227    "HTTPAPIResponseHeaders": {},
228    "LeaveOnInt": false,
229    "LeaveOnTerm": false,
230    "LogLevel": "DEBUG",
231    "NodeName": "",
232    "Ports": {
233      "HTTP": 4646,
234      "RPC": 4647,
235      "Serf": 4648
236    },
237    "Region": "global",
238    "Revision": "f551dcb83e3ac144c9dbb90583b6e82d234662e9",
239    "Server": {
240      "BootstrapExpect": 0,
241      "DataDir": "",
242      "Enabled": true,
243      "EnabledSchedulers": null,
244      "HeartbeatGrace": "",
245      "NodeGCThreshold": "",
246      "NumSchedulers": 0,
247      "ProtocolVersion": 0,
248      "RejoinAfterLeave": false,
249      "RetryInterval": "30s",
250      "RetryJoin": [],
251      "RetryMaxAttempts": 0,
252      "StartJoin": []
253    },
254    "SyslogFacility": "LOCAL0",
255    "TLSConfig": {
256      "CAFile": "",
257      "CertFile": "",
258      "EnableHTTP": false,
259      "EnableRPC": false,
260      "KeyFile": "",
261      "VerifyServerHostname": false
262    },
263    "Telemetry": {
264      "CirconusAPIApp": "",
265      "CirconusAPIToken": "",
266      "CirconusAPIURL": "",
267      "CirconusBrokerID": "",
268      "CirconusBrokerSelectTag": "",
269      "CirconusCheckDisplayName": "",
270      "CirconusCheckForceMetricActivation": "",
271      "CirconusCheckID": "",
272      "CirconusCheckInstanceID": "",
273      "CirconusCheckSearchTag": "",
274      "CirconusCheckSubmissionURL": "",
275      "CirconusCheckTags": "",
276      "CirconusSubmissionInterval": "",
277      "CollectionInterval": "1s",
278      "DataDogAddr": "",
279      "DataDogTags": [],
280      "DisableHostname": false,
281      "PublishAllocationMetrics": false,
282      "PublishNodeMetrics": false,
283      "StatsdAddr": "",
284      "StatsiteAddr": "",
285      "UseNodeName": false
286    },
287    "Vault": {
288      "Addr": "https://vault.service.consul:8200",
289      "AllowUnauthenticated": true,
290      "ConnectionRetryIntv": 30000000000,
291      "Enabled": null,
292      "Role": "",
293      "TLSCaFile": "",
294      "TLSCaPath": "",
295      "TLSCertFile": "",
296      "TLSKeyFile": "",
297      "TLSServerName": "",
298      "TLSSkipVerify": null,
299      "TaskTokenTTL": "",
300      "Token": "root"
301    },
302    "Version": "0.5.5",
303    "VersionPrerelease": "dev"
304  },
305  "member": {
306    "Addr": "127.0.0.1",
307    "DelegateCur": 4,
308    "DelegateMax": 4,
309    "DelegateMin": 2,
310    "Name": "bacon-mac.global",
311    "Port": 4648,
312    "ProtocolCur": 2,
313    "ProtocolMax": 5,
314    "ProtocolMin": 1,
315    "Status": "alive",
316    "Tags": {
317      "role": "nomad",
318      "region": "global",
319      "dc": "dc1",
320      "vsn": "1",
321      "mvn": "1",
322      "build": "0.5.5dev",
323      "port": "4647",
324      "bootstrap": "1"
325    }
326  },
327  "stats": {
328    "runtime": {
329      "cpu_count": "8",
330      "kernel.name": "darwin",
331      "arch": "amd64",
332      "version": "go1.8",
333      "max_procs": "7",
334      "goroutines": "79"
335    },
336    "nomad": {
337      "server": "true",
338      "leader": "true",
339      "leader_addr": "127.0.0.1:4647",
340      "bootstrap": "false",
341      "known_regions": "1"
342    },
343    "raft": {
344      "num_peers": "0",
345      "fsm_pending": "0",
346      "last_snapshot_index": "0",
347      "last_log_term": "2",
348      "commit_index": "144",
349      "term": "2",
350      "last_log_index": "144",
351      "protocol_version_max": "3",
352      "snapshot_version_max": "1",
353      "latest_configuration_index": "1",
354      "latest_configuration": "[{Suffrage:Voter ID:127.0.0.1:4647 Address:127.0.0.1:4647}]",
355      "last_contact": "never",
356      "applied_index": "144",
357      "protocol_version": "1",
358      "protocol_version_min": "0",
359      "snapshot_version_min": "0",
360      "state": "Leader",
361      "last_snapshot_term": "0"
362    },
363    "client": {
364      "heartbeat_ttl": "17.79568937s",
365      "node_id": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
366      "known_servers": "127.0.0.1:4647",
367      "num_allocations": "0",
368      "last_heartbeat": "10.107423052s"
369    },
370    "serf": {
371      "event_time": "1",
372      "event_queue": "0",
373      "encrypted": "false",
374      "member_time": "1",
375      "query_time": "1",
376      "intent_queue": "0",
377      "query_queue": "0",
378      "members": "1",
379      "failed": "0",
380      "left": "0",
381      "health_score": "0"
382    }
383  }
384}
385```
386
387## Join Agent
388
389This endpoint introduces a new member to the gossip pool. This endpoint is only
390eligible for servers.
391
392| Method | Path          | Produces           |
393| ------ | ------------- | ------------------ |
394| `POST` | `/agent/join` | `application/json` |
395
396The table below shows this endpoint's support for
397[blocking queries](/api-docs#blocking-queries) and
398[required ACLs](/api-docs#acls).
399
400| Blocking Queries | ACL Required |
401| ---------------- | ------------ |
402| `NO`             | `none`       |
403
404### Parameters
405
406- `address` `(string: <required>)` - Specifies the address to join in the
407  `ip:port` format. This is provided as a query parameter and may be specified
408  multiple times to join multiple servers.
409
410### Sample Request
411
412```shell-session
413$ curl \
414    --request POST \
415    https://localhost:4646/v1/agent/join?address=1.2.3.4&address=5.6.7.8
416```
417
418### Sample Response
419
420```json
421{
422  "error": "",
423  "num_joined": 2
424}
425```
426
427## Force Leave Agent
428
429This endpoint forces a member of the gossip pool from the `"failed"` state to
430the `"left"` state. This allows the consensus protocol to remove the peer and
431stop attempting replication. This is only applicable for servers.
432
433| Method | Path                 | Produces           |
434| ------ | -------------------- | ------------------ |
435| `POST` | `/agent/force-leave` | `application/json` |
436
437The table below shows this endpoint's support for
438[blocking queries](/api-docs#blocking-queries) and
439[required ACLs](/api-docs#acls).
440
441| Blocking Queries | ACL Required  |
442| ---------------- | ------------- |
443| `NO`             | `agent:write` |
444
445### Parameters
446
447- `node` `(string: <required>)` - Specifies the name of the node to force leave.
448
449### Sample Request
450
451```shell-session
452$ curl \
453    --request POST \
454    https://localhost:4646/v1/agent/force-leave?node=client-ab2e23dc
455```
456
457## Health
458
459This endpoint returns whether or not the agent is healthy. When using Consul it
460is the endpoint Nomad will register for its own health checks.
461
462When the agent is unhealthy 500 will be returned along with JSON response
463containing an error message.
464
465| Method | Path            | Produces           |
466| ------ | --------------- | ------------------ |
467| `GET`  | `/agent/health` | `application/json` |
468
469The table below shows this endpoint's support for
470[blocking queries](/api-docs#blocking-queries) and
471[required ACLs](/api-docs#acls).
472
473| Blocking Queries | ACL Required |
474| ---------------- | ------------ |
475| `NO`             | `none`       |
476
477### Sample Request
478
479```shell-session
480$ curl \
481    https://localhost:4646/v1/agent/health
482```
483
484### Sample Response
485
486```json
487{
488  "client": {
489    "message": "ok",
490    "ok": true
491  },
492  "server": {
493    "message": "ok",
494    "ok": true
495  }
496}
497```
498
499## Host
500
501This endpoint returns data about the agent's host environment from the
502perspective of the agent. It is included in the archive produced by
503nomad operator debug. Known sensitive environment variables are shown as
504`<redacted>`, but the response may still contain sensitive
505information.
506
507| Method | Path          | Produces           |
508| ------ | ------------- | ------------------ |
509| `GET`  | `/agent/host` | `application/json` |
510
511The table below shows this endpoint's support for
512[blocking queries](/api-docs#blocking-queries) and
513[required ACLs](/api-docs#acls).
514
515| Blocking Queries | ACL Required |
516| ---------------- | ------------ |
517| `NO`             | `agent:read` |
518
519### Parameters
520
521- `server_id` `(string: <optional>)` - Specify the server name for
522  targeting.
523
524- `node_id` `(string: <optional>)` - Specify the client node id for
525  targeting.
526
527### Sample Request
528
529```shell-session
530$ curl \
531    https://localhost:4646/v1/agent/host?node_id=4bb9aca7-d43b-43fc-d604-3a271ef0a6c0
532```
533
534### Sample Response
535
536```json
537{
538  "AgentID": "4bb9aca7-d43b-43fc-d604-3a271ef0a6c0",
539  "HostData": {
540    "OS": "x86_64 ip-172-31-92-147 4.15.0-1007-aws Linux #7-Ubuntu SMP Tue Apr 24 10:56:17 UTC 2018",
541    "Network": [
542      {
543        "DialPacket": "\"udp4\" \"\"",
544        "DialStream": "\"tcp4\" \"\"",
545        "ListenPacket": "\"udp4\" \"\"",
546        "ListenStream": "\"tcp4\" \"\"",
547        "address": "127.0.0.1",
548        "binary": "01111111000000000000000000000001",
549        "broadcast": "127.255.255.255",
550        "first_usable": "127.0.0.1",
551        "hex": "7f000001",
552        "host": "127.0.0.1",
553        "last_usable": "127.255.255.254",
554        "mask_bits": "8",
555        "netmask": "255.0.0.0",
556        "network": "127.0.0.0",
557        "octets": "127 0 0 1",
558        "port": "0",
559        "size": "16777216",
560        "string": "127.0.0.1/8",
561        "type": "IPv4",
562        "uint32": "2130706433"
563      }
564    ],
565    "ResolvConf": "nameserver 172.17.0.1\nnameserver 8.8.8.8\n",
566    "Hosts": "127.0.0.1 localhost\n\n# The following lines are desirable for IPv6 capable hosts\n::1 ip6-localhost ip6-loopback\nfe00::0 ip6-localnet\nff00::0 ip6-mcastprefix\nff02::1 ip6-allnodes\nff02::2 ip6-allrouters\nff02::3 ip6-allhosts\n127.0.0.1 ip-172-31-71-163\n127.0.0.1 ip-172-31-92-147\n",
567    "Environment": {
568      "INVOCATION_ID": "b106b6ac67764c9b9f85c5cc5c3357e5",
569      "JOURNAL_STREAM": "9:109527",
570      "LANG": "C.UTF-8",
571      "PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
572    },
573    "Disk": {
574      "/": {
575        "DiskMB": 7876,
576        "UsedMB": 4287
577      }
578    }
579  }
580}
581```
582
583## Stream Logs
584
585This endpoint streams logs from the local agent until the connection is closed
586
587| Method | Path             | Produces           |
588| ------ | ---------------- | ------------------ |
589| `GET`  | `/agent/monitor` | `application/json` |
590
591The table below shows this endpoint's support for
592[blocking queries](/api-docs#blocking-queries) and
593[required ACLs](/api-docs#acls).
594
595| Blocking Queries | ACL Required |
596| ---------------- | ------------ |
597| `NO`             | `agent:read` |
598
599### Parameters
600
601- `log_level` `(string: "info")` - Specifies a text string containing a log level
602  to filter on, such as `info`. Possible values include `trace`, `debug`,
603  `info`, `warn`, `error`
604
605- `log_json` `(bool: false)` - Specifies if the log format for streamed logs
606  should be JSON.
607
608- `node_id` `(string: "a57b2adb-1a30-2dda-8df0-25abb0881952")` - Specifies a text
609  string containing a node-id to target for streaming.
610
611- `server_id` `(string: "server1.global")` - Specifies a text
612  string containing a server name or "leader" to target a specific remote server
613  or leader for streaming.
614
615- `plain` `(bool: false)` - Specifies if the response should be JSON or
616  plaintext
617
618### Sample Request
619
620```shell-session
621$ curl \
622    https://localhost:4646/v1/agent/monitor?log_level=debug&server_id=leader
623
624$ curl \
625    https://localhost:4646/v1/agent/monitor?log_level=debug&node_id=a57b2adb-1a30-2dda-8df0-25abb0881952
626```
627
628### Sample Response
629
630```json
631{
632  "Offset": 0,
633  "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..."
634  "FileEvent": "log"
635}
636```
637
638#### Field Reference
639
640The return value is a stream of frames. These frames contain the following
641fields:
642
643- `Data` - A base64 encoding of the bytes being streamed.
644
645- `FileEvent` - An event that could cause a change in the streams position. The
646  possible value for this endpoint is "log".
647
648- `Offset` - Offset is the offset into the stream.
649
650## Agent Runtime Profiles
651
652This endpoint is the equivalent of Go's /debug/pprof endpoint but is protected
653by ACLs and supports remote forwarding to a client node or server. See the
654[Golang documentation](https://golang.org/pkg/runtime/pprof/#Profile) for a list of available profiles.
655
656| Method | Path                           | Produces                   |
657| ------ | ------------------------------ | -------------------------- |
658| `GET`  | `/agent/pprof/cmdline`         | `text/plain`               |
659| `GET`  | `/agent/pprof/profile`         | `application/octet-stream` |
660| `GET`  | `/agent/pprof/trace`           | `application/octet-stream` |
661| `GET`  | `/agent/pprof/<pprof profile>` | `application/octet-stream` |
662
663The table below shows this endpoint's support for
664[blocking queries](/api-docs#blocking-queries) and
665[required ACLs](/api-docs#acls).
666
667| Blocking Queries | ACL Required  |
668| ---------------- | ------------- |
669| `NO`             | `agent:write` |
670
671### Default Behavior
672
673This endpoint is enabled whenever ACLs are enabled. Due to the potentially
674sensitive nature of data contained in profiles, as well as their significant
675performance impact, the agent/pprof endpoint is protected by a high level ACL:
676`agent:write`. For these reasons its recommended to leave [`enable_debug`](/docs/configuration#enable_debug)
677unset and only use the ACL-protected endpoints.
678
679The following table explains when each endpoint is available:
680
681| Endpoint        | `enable_debug` | ACLs | **Available?** |
682| --------------- | -------------- | ---- | -------------- |
683| /v1/agent/pprof | unset          | n/a  | no             |
684| /v1/agent/pprof | `true`         | n/a  | yes            |
685| /v1/agent/pprof | `false`        | n/a  | no             |
686| /v1/agent/pprof | unset          | off  | no             |
687| /v1/agent/pprof | unset          | on   | **yes**        |
688| /v1/agent/pprof | `true`         | off  | yes            |
689| /v1/agent/pprof | `false`        | on   | **yes**        |
690
691### Parameters
692
693- `node_id` `(string: "a57b2adb-1a30-2dda-8df0-25abb0881952")` - Specifies a text
694  string containing a Node ID to target for profiling.
695
696- `server_id` `(string: "server1.global")` - Specifies a text
697  string containing a Server ID, name, or `leader` to target a specific remote
698  server or leader for profiling.
699
700- `seconds` `(int: 3)` - Specifies the amount of time to run a profile or trace
701  request for.
702
703- `debug` `(int: 1)` - Specifies if a given pprof profile should be returned as
704  human readable plain text instead of the pprof binary format. Defaults to 0,
705  setting to 1 enables human readable plain text.
706
707### Sample Request
708
709```shell-session
710$ curl -O -J \
711    --header "X-Nomad-Token: 8176afd3-772d-0b71-8f85-7fa5d903e9d4" \
712    https://localhost:4646/v1/agent/pprof/goroutine?server_id=leader
713
714$ go tool pprof goroutine
715
716$ curl -O -J \
717    --header "X-Nomad-Token: 8176afd3-772d-0b71-8f85-7fa5d903e9d4" \
718    https://localhost:4646/v1/agent/profile?seconds=5&node_id=a57b2adb-1a30-2dda-8df0-25abb0881952
719
720$ go tool pprof profile
721
722$ curl -O -J \
723    --header "X-Nomad-Token: 8176afd3-772d-0b71-8f85-7fa5d903e9d4" \
724    https://localhost:4646/v1/agent/trace?&seconds=5&server_id=server1.global
725
726go tool trace trace
727```
728