# Get deployment targets

Source: https://www.jawsdeploy.net/rest-api/deployments-targets | Section: Deployments

Find out which machines and cloud targets each step of a deployment matched, and which of them actually ran it.

`GET /api/deployment/targets`

Lists, for every step of a deployment, the targets it matched and what the step did on each one. Use it instead of reading the deployment log when you need to know which machines are on the new version.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `deploymentId` | query | string | yes | ID of the deployment. |
| `targets` | query | string | no | `matched` (the default) lists every target each step matched, each with its outcome. `executed` lists only the targets the step was actually started on - outcomes `executed`, `failed`, `timedOut` and `cancelled`. |

### Outcomes

- `executed` - the step ran on the target and reported no errors.
- `failed` - the step ran on the target and failed. This includes a script that logged errors while the agent still reported the step as completed.
- `timedOut` - the step ran on the target and the server stopped waiting for it.
- `cancelled` - the step was running on the target when it was cancelled.
- `skipped` - the step's execute condition was not met on this target.
- `notRun` - the step never started on this target. Usually an earlier failure stopped the rollout, or the deployment was stopped before it reached this step. A deployment that is still running also shows `notRun` for steps it has not reached yet.
- `error` - the deployment hit an unexpected error on this target, before or while running the step.

### Matched versus executed

The matched targets are worked out when the deployment is created. The deployment works them out again when it runs, so a machine added or disabled in between can make the two differ. Both are reported: a target that ran the step but was not in the matched list is still returned, after the matched ones.

### Cloud targets

A step that runs on a worker against cloud targets drives all of its targets in one run on the worker, so every target of that step shares the same outcome. The worker itself is not listed.

## Response fields

| Field | Type | Description |
|---|---|---|
| `deploymentId` | string | The deployment you asked about. |
| `targetsFilter` | string | `matched` or `executed`, echoing the request. |
| `outcomesAvailable` | boolean | `false` when no outcomes have been recorded for this deployment - it ran before Jaws recorded them, or has not finished its first step yet. Every `outcome` is then `null`. Do not read that as "not executed". |
| `steps` | object[] | Every step of the release, in order - including steps that matched nothing. |
| `steps[].order` | number | Position of the step in the release, starting at 1 - the same number the deployment log shows. |
| `steps[].stepId` | string | ID of the step in the release. |
| `steps[].name` | string | Name of the step. |
| `steps[].rollingGroupId` | string | The rolling group the step belongs to, or `null`. |
| `steps[].targets` | object[] | The step's targets. Empty for a step that was excluded or matched nothing. |
| `steps[].targets[].machineId` | string | Set for a machine. Exactly one of `machineId` and `cloudTargetId` is set. |
| `steps[].targets[].cloudTargetId` | string | Set for a cloud target. |
| `steps[].targets[].name` | string | Name of the machine or cloud target. |
| `steps[].targets[].groupNumber` | number | The rollout group the machine was in, starting at 1. `null` for cloud targets. |
| `steps[].targets[].outcome` | string (enum) | `executed`, `failed`, `timedOut`, `cancelled`, `skipped`, `notRun` or `error`, or `null` when `outcomesAvailable` is `false`. See below. |

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid or unknown `deploymentId`, or `targets` is not `matched` or `executed`. |
| 401 | Missing or invalid Basic auth credentials, or the service account lacks the required role. |

Example request:

```
GET /api/deployment/targets?deploymentId=dep_a1b2c3&targets=matched HTTP/1.1
Authorization: Basic <base64(...)>
```

Example response:

```
{
  "deploymentId": "dep_a1b2c3",
  "targetsFilter": "matched",
  "outcomesAvailable": true,
  "steps": [
    {
      "order": 3,
      "stepId": "step_123",
      "name": "Deploy web app",
      "rollingGroupId": null,
      "targets": [
        { "machineId": "m_1", "cloudTargetId": null, "name": "web-01", "groupNumber": 1, "outcome": "executed" },
        { "machineId": "m_2", "cloudTargetId": null, "name": "web-02", "groupNumber": 1, "outcome": "failed" },
        { "machineId": "m_3", "cloudTargetId": null, "name": "web-03", "groupNumber": 2, "outcome": "notRun" }
      ]
    },
    {
      "order": 4,
      "stepId": "step_456",
      "name": "Update function",
      "rollingGroupId": null,
      "targets": [
        { "machineId": null, "cloudTargetId": "ct_1", "name": "prod-fn", "groupNumber": null, "outcome": "skipped" }
      ]
    }
  ]
}
```