--- 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. - `namespace` `(string: "default")` - Specifies the namespace to search. Specifying `*` would return all allocations across all the authorized namespaces. - `resources` `(bool: false)` - Specifies whether or not to include the `AllocatedResources` field in the response. - `task_states` `(bool: true)` - Specifies whether or not to include the `TaskStates` field in the response. TaskStates are included by default but can represent a large percentage of the overall response size. Clusters with a large number of allocations may set `task_states=false` to significantly reduce the size of the response. ### Sample Request ```shell-session $ curl \ https://localhost:4646/v1/allocations ``` ```shell-session $ curl \ https://localhost:4646/v1/allocations?prefix=a8198d79 ``` ```shell-session $ curl \ https://localhost:4646/v1/allocations?namespace=*&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: )`- 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: )`- 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: )`- 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: )`- 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 {} ```