github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/api-docs/allocations.mdx

---
layout: api
page_title: Allocations - HTTP API
sidebar_title: Allocations
description: The /allocation endpoints are used to query for and interact with allocations.
---

# Allocations HTTP API

The `/allocation` endpoints are used to query for and interact with allocations.

## List Allocations

This endpoint lists all allocations.

| Method | Path              | Produces           |
| ------ | ----------------- | ------------------ |
| `GET`  | `/v1/allocations` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required         |
| ---------------- | -------------------- |
| `YES`            | `namespace:read-job` |

### Parameters

- `prefix` `(string: "")`- Specifies a string to filter allocations based on an
  ID prefix. Because the value is decoded to bytes, the prefix must have an
  even number of hexadecimal characters (0-9a-f). This is specified as a query
  string parameter.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/allocations
```

```shell-session
$ curl \
    https://localhost:4646/v1/allocations?prefix=a8198d79
```

### Sample Response

```json
[
  {
    "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
    "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
    "Name": "example.cache[0]",
    "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
    "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
    "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
    "RescheduleTracker": {
      "Events": [
        {
          "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
          "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
          "RescheduleTime": 1517434161192946200,
          "Delay": "5000000000"
        }
      ]
    },
    "JobID": "example",
    "TaskGroup": "cache",
    "DesiredStatus": "run",
    "DesiredDescription": "",
    "ClientStatus": "running",
    "ClientDescription": "",
    "TaskStates": {
      "redis": {
        "State": "running",
        "FinishedAt": "0001-01-01T00:00:00Z",
        "LastRestart": "0001-01-01T00:00:00Z",
        "Restarts": 0,
        "StartedAt": "2017-07-25T23:36:26.106431265Z",
        "Failed": false,
        "Events": [
          {
            "Type": "Received",
            "Time": 1495747371795703800,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": ""
          },
          {
            "Type": "Driver",
            "Time": 1495747371798867200,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": "Downloading image redis:3.2"
          },
          {
            "Type": "Started",
            "Time": 1495747379525667800,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": ""
          }
        ]
      }
    },
    "CreateIndex": 54,
    "ModifyIndex": 57,
    "CreateTime": 1495747371794276400,
    "ModifyTime": 1495747371794276400
  }
]
```

## Read Allocation

This endpoint reads information about a specific allocation.

| Method | Path                       | Produces           |
| ------ | -------------------------- | ------------------ |
| `GET`  | `/v1/allocation/:alloc_id` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required         |
| ---------------- | -------------------- |
| `YES`            | `namespace:read-job` |

### Parameters

- `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
  must be the full UUID, not the short 8-character one. This is specified as
  part of the path.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577
```

### Sample Response

```json
{
  "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
  "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
  "Name": "example.cache[0]",
  "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
  "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
  "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
  "RescheduleTracker": {
    "Events": [
      {
        "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
        "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
        "RescheduleTime": 1517434161192946200,
        "Delay": "5000000000"
      }
    ]
  },
  "JobID": "example",
  "Job": {
    "Region": "global",
    "ID": "example",
    "ParentID": "",
    "Name": "example",
    "Type": "service",
    "Priority": 50,
    "AllAtOnce": false,
    "Datacenters": ["dc1"],
    "Constraints": null,
    "Affinities": null,
    "TaskGroups": [
      {
        "Name": "cache",
        "Count": 1,
        "Constraints": null,
        "Affinities": null,
        "RestartPolicy": {
          "Attempts": 10,
          "Interval": 300000000000,
          "Delay": 25000000000,
          "Mode": "delay"
        },
        "Spreads": null,
        "Tasks": [
          {
            "Name": "redis",
            "Driver": "docker",
            "User": "",
            "Config": {
              "port_map": [
                {
                  "db": 6379
                }
              ],
              "image": "redis:3.2"
            },
            "Env": null,
            "Services": [
              {
                "Name": "redis-cache",
                "PortLabel": "db",
                "Tags": ["global", "cache"],
                "Checks": [
                  {
                    "Name": "alive",
                    "Type": "tcp",
                    "Command": "",
                    "Args": null,
                    "Path": "",
                    "Protocol": "",
                    "PortLabel": "",
                    "Interval": 10000000000,
                    "Timeout": 2000000000,
                    "InitialStatus": ""
                  }
                ]
              }
            ],
            "Vault": null,
            "Templates": null,
            "Constraints": null,
            "Affinities": null,
            "Resources": {
              "CPU": 500,
              "MemoryMB": 10,
              "DiskMB": 0,
              "Networks": [
                {
                  "Device": "",
                  "CIDR": "",
                  "IP": "",
                  "MBits": 10,
                  "ReservedPorts": null,
                  "DynamicPorts": [
                    {
                      "Label": "db",
                      "Value": 0
                    }
                  ]
                }
              ]
            },
            "Spreads": null,
            "DispatchPayload": null,
            "Meta": null,
            "KillTimeout": 5000000000,
            "LogConfig": {
              "MaxFiles": 10,
              "MaxFileSizeMB": 10
            },
            "Artifacts": null,
            "Leader": false
          }
        ],
        "EphemeralDisk": {
          "Sticky": false,
          "SizeMB": 300,
          "Migrate": false
        },
        "Meta": null
      }
    ],
    "Update": {
      "Stagger": 10000000000,
      "MaxParallel": 0
    },
    "Periodic": null,
    "ParameterizedJob": null,
    "Payload": null,
    "Spreads": null,
    "Meta": null,
    "VaultToken": "",
    "Status": "pending",
    "StatusDescription": "",
    "CreateIndex": 52,
    "ModifyIndex": 52,
    "JobModifyIndex": 52
  },
  "TaskGroup": "cache",
  "Resources": {
    "CPU": 500,
    "MemoryMB": 10,
    "DiskMB": 300,
    "Networks": [
      {
        "Device": "lo0",
        "CIDR": "",
        "IP": "127.0.0.1",
        "MBits": 10,
        "ReservedPorts": null,
        "DynamicPorts": [
          {
            "Label": "db",
            "Value": 23116
          }
        ]
      }
    ]
  },
  "SharedResources": {
    "CPU": 0,
    "MemoryMB": 0,
    "DiskMB": 300,
    "Networks": null
  },
  "TaskResources": {
    "redis": {
      "CPU": 500,
      "MemoryMB": 10,
      "DiskMB": 0,
      "Networks": [
        {
          "Device": "lo0",
          "CIDR": "",
          "IP": "127.0.0.1",
          "MBits": 10,
          "ReservedPorts": null,
          "DynamicPorts": [
            {
              "Label": "db",
              "Value": 23116
            }
          ]
        }
      ]
    }
  },
  "Metrics": {
    "NodesEvaluated": 1,
    "NodesFiltered": 0,
    "NodesAvailable": {
      "dc1": 1
    },
    "ClassFiltered": null,
    "ConstraintFiltered": null,
    "NodesExhausted": 0,
    "ClassExhausted": null,
    "DimensionExhausted": null,
    "Scores": {
      "fb2170a8-257d-3c64-b14d-bc06cc94e34c.binpack": 0.6205732522109244
    },
    "AllocationTime": 31729,
    "CoalescedFailures": 0
  },
  "DesiredStatus": "run",
  "DesiredDescription": "",
  "ClientStatus": "running",
  "ClientDescription": "",
  "TaskStates": {
    "redis": {
      "State": "running",
      "Failed": false,
      "FinishedAt": "0001-01-01T00:00:00Z",
      "LastRestart": "0001-01-01T00:00:00Z",
      "Restarts": 0,
      "StartedAt": "2017-07-25T23:36:26.106431265Z",
      "Events": [
        {
          "Type": "Received",
          "Time": 1495747371795703800,
          "FailsTask": false,
          "RestartReason": "",
          "SetupError": "",
          "DriverError": "",
          "ExitCode": 0,
          "Signal": 0,
          "Message": "",
          "KillTimeout": 0,
          "KillError": "",
          "KillReason": "",
          "StartDelay": 0,
          "DownloadError": "",
          "ValidationError": "",
          "DiskLimit": 0,
          "FailedSibling": "",
          "VaultError": "",
          "TaskSignalReason": "",
          "TaskSignal": "",
          "DriverMessage": ""
        },
        {
          "Type": "Driver",
          "Time": 1495747371798867200,
          "FailsTask": false,
          "RestartReason": "",
          "SetupError": "",
          "DriverError": "",
          "ExitCode": 0,
          "Signal": 0,
          "Message": "",
          "KillTimeout": 0,
          "KillError": "",
          "KillReason": "",
          "StartDelay": 0,
          "DownloadError": "",
          "ValidationError": "",
          "DiskLimit": 0,
          "FailedSibling": "",
          "VaultError": "",
          "TaskSignalReason": "",
          "TaskSignal": "",
          "DriverMessage": "Downloading image redis:3.2"
        },
        {
          "Type": "Started",
          "Time": 1495747379525667800,
          "FailsTask": false,
          "RestartReason": "",
          "SetupError": "",
          "DriverError": "",
          "ExitCode": 0,
          "Signal": 0,
          "Message": "",
          "KillTimeout": 0,
          "KillError": "",
          "KillReason": "",
          "StartDelay": 0,
          "DownloadError": "",
          "ValidationError": "",
          "DiskLimit": 0,
          "FailedSibling": "",
          "VaultError": "",
          "TaskSignalReason": "",
          "TaskSignal": "",
          "DriverMessage": ""
        }
      ]
    }
  },
  "PreviousAllocation": "",
  "CreateIndex": 54,
  "ModifyIndex": 57,
  "AllocModifyIndex": 54,
  "CreateTime": 1495747371794276400,
  "ModifyTime": 1495747371794276400
}
```

#### Field Reference

- `TaskStates` - A map of tasks to their current state and the latest events
  that have effected the state. `TaskState` objects contain the following
  fields:

  - `State`: The task's current state. It can have one of the following
    values:

    - `TaskStatePending` - The task is waiting to be run, either for the first
      time or due to a restart.

    - `TaskStateRunning` - The task is currently running.

    - `TaskStateDead` - The task is dead and will not run again.

  - `StartedAt`: The time the task was last started at. Can be updated through
    restarts.

  - `FinishedAt`: The time the task was finished at.

  - `LastRestart`: The last time the task was restarted.

  - `Restarts`: The number of times the task has restarted.

  - `Events` - An event contains metadata about the event. The latest 10 events
    are stored per task. Each event is timestamped (Unix nanoseconds) and has one
    of the following types:

    - `Setup Failure` - The task could not be started because there was a
      failure setting up the task prior to it running.

    - `Driver Failure` - The task could not be started due to a failure in the
      driver.

    - `Started` - The task was started; either for the first time or due to a
      restart.

    - `Terminated` - The task was started and exited.

    - `Killing` - The task has been sent the kill signal.

    - `Killed` - The task was killed by a user.

    - `Received` - The task has been pulled by the client at the given timestamp.

    - `Failed Validation` - The task was invalid and as such it didn't run.

    - `Restarting` - The task terminated and is being restarted.

    - `Not Restarting` - the task has failed and is not being restarted because
      it has exceeded its restart policy.

    - `Downloading Artifacts` - The task is downloading the artifact(s)
    - specified in the task.

    - `Failed Artifact Download` - Artifact(s) specified in the task failed to
      download.

    - `Restart Signaled` - The task was singled to be restarted.

    - `Signaling` - The task was is being sent a signal.

    - `Sibling Task Failed` - A task in the same task group failed.

    - `Leader Task Dead` - The group's leader task is dead.

    - `Driver` - A message from the driver.

    - `Task Setup` - Task setup messages.

    - `Building Task Directory` - Task is building its file system.

    Depending on the type the event will have applicable annotations.

## Stop Allocation

This endpoint stops and reschedules a specific allocation.

| Method         | Path                            | Produces           |
| -------------- | ------------------------------- | ------------------ |
| `POST` / `PUT` | `/v1/allocation/:alloc_id/stop` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required                |
| ---------------- | --------------------------- |
| `NO`             | `namespace:alloc-lifecycle` |

### Parameters

- `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
  must be the full UUID, not the short 8-character one. This is specified as
  part of the path.

### Sample Request

```shell-session
$ curl -X POST \
    https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/stop
```

### Sample Response

```json
{
  "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
  "Index": 54
}
```

## Signal Allocation

This endpoint sends a signal to an allocation or task.

| Method         | Path                                     | Produces           |
| -------------- | ---------------------------------------- | ------------------ |
| `POST` / `PUT` | `/v1/client/allocation/:alloc_id/signal` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required                |
| ---------------- | --------------------------- |
| `NO`             | `namespace:alloc-lifecycle` |

### Parameters

- `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
  must be the full UUID, not the short 8-character one. This is specified as
  part of the path.

### Sample Payload

```json
{
  "Signal": "SIGUSR1",
  "Task": "FOO"
}
```

### Sample Request

```shell-session
$ curl -X POST -d '{"Signal": "SIGUSR1" }' \
    https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/signal
```

### Sample Response

```json
{}
```

## Restart Allocation

This endpoint restarts an allocation or task in-place.

| Method         | Path                                      | Produces           |
| -------------- | ----------------------------------------- | ------------------ |
| `POST` / `PUT` | `/v1/client/allocation/:alloc_id/restart` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required                |
| ---------------- | --------------------------- |
| `NO`             | `namespace:alloc-lifecycle` |

### Parameters

- `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
  must be the full UUID, not the short 8-character one. This is specified as
  part of the path.

### Sample Payload

```json
{
  "Task": "FOO"
}
```

### Sample Request

```shell-session
$ curl -X POST -d '{"Task": "redis" }' \
    https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/restart
```

### Sample Response

```json
{}
```