> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Template Deploy Job

> Returns the state of a template deploy or update job, with its steps, the resources it created, the error if it failed and the outputs of a finished job.

Returns a deploy or update job started by [Deploy Template](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy.md) or [Update from Template](https://docs.vertracloud.app/api-reference/endpoint/templates/update.md). With an API key the scope is `templates:deploy`. Only the account that started the job can read it; any other job ID is `TEMPLATE_DEPLOY_NOT_FOUND`. The response is never cached. For live progress without polling, use the [event stream](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy-events.md).

**deploy\_id** `string` *required*

The ID of the job, returned when the deploy or update was accepted.

### Response

**response** `object`

The job.

**Toggle object**

**id** `string`

The job ID.

**kind** `string`

`deploy` when the job created resources from a template, `update` when it moved existing ones to a newer version.

**template\_id** `string`

The template ID.

**version\_id** `string`

The ID of the version being deployed.

**version** `string`

The version number being deployed.

**status** `string`

`queued`, `running`, `undoing` (a step failed and what the job created is being removed), `succeeded` or `failed`. A job that is `failed` has already undone everything it created. `succeeded` and `failed` are final.

**current\_step** `string | null`

The step running now, or `null` when the job is queued or finished.

**steps** `object[]`

The steps that apply to the job, in execution order. Each has `step`, `status`, `started_at` and `finished_at` (`null` until they happen). A step is `pending`, `running`, `done`, `skipped` (it does not apply, for example when there is no database) or `failed`. Steps: `validate`, `snapshot` (updates only: a safety snapshot before anything changes), `network`, `databases`, `blob`, `images`, `apps`, `variables`, `certificates`, `start`, `healthcheck`, `outputs` and `rollback` (updates only, when a failed update goes back to the snapshot).

**error** `object | null`

Set when `status` is `failed`.

**Toggle object**

**code** `string`

An error code, such as `TEMPLATE_DEPLOY_FAILED`, `BUILD_FAILED`, `MAX_APPS_REACHED` or `TEMPLATE_PLAN_REQUIRED`.

**message** `string`

A fixed, readable sentence in English. It never carries values from your variables.

**step** `string | null`

The step that failed.

**details** `object`

Optional context. For an update that could not go back to the snapshot it holds `rollback_failed`.

**resources** `object[]`

What the job created, in order. Each has `resource_type`, `resource_id`, `service_id` (the service in the manifest, `null` for the stack and images) and `name`. It is empty after a failure, since the job undoes what it created.

**stack\_id** `string | null`

The stack, when the template has two or more services.

**application\_id** `string | null`

The application, when the template has a single application.

**outputs** `object[]`

The outputs of a succeeded job; empty before that.

**Toggle object**

**label** `object`

The label in the three languages.

**value** `string | object | null`

The value: a text, or a text per language. For an output with `once`, the value comes back **only on the first read** of the finished job and is `null` afterwards.

**secret** `boolean`

`true` when the value is a secret.

**once** `boolean`

`true` when the value is shown only once.

**created\_at** `string`

When the job was accepted.

**updated\_at** `string`

When the job last changed.

**finished\_at** `string | null`

When the job ended, or `null`.

```bash cURL theme={null}
curl https://api.vertracloud.app/v1/template-deploys/3f6a9c12-7e4b-4d58-a1c0-5b8e2d9f7a63 \
  -H "Authorization: Bearer $VERTRA_API_KEY"
```

```json Response (succeeded) theme={null}
{
  "response": {
    "id": "3f6a9c12-7e4b-4d58-a1c0-5b8e2d9f7a63",
    "kind": "deploy",
    "template_id": "7c1d4f0e-3b8a-4d52-9a66-1f0c2e5a9b41",
    "version_id": "e0b7a2c9-5d14-4f8e-8c3a-92d6b1f47a10",
    "version": "1.0.0",
    "status": "succeeded",
    "current_step": null,
    "steps": [
      { "step": "validate", "status": "done", "started_at": "2026-10-28T14:00:01Z", "finished_at": "2026-10-28T14:00:02Z" },
      { "step": "apps", "status": "done", "started_at": "2026-10-28T14:00:02Z", "finished_at": "2026-10-28T14:00:20Z" },
      { "step": "variables", "status": "done", "started_at": "2026-10-28T14:00:20Z", "finished_at": "2026-10-28T14:00:21Z" },
      { "step": "start", "status": "done", "started_at": "2026-10-28T14:00:21Z", "finished_at": "2026-10-28T14:00:30Z" },
      { "step": "healthcheck", "status": "done", "started_at": "2026-10-28T14:00:30Z", "finished_at": "2026-10-28T14:00:41Z" },
      { "step": "outputs", "status": "done", "started_at": "2026-10-28T14:00:41Z", "finished_at": "2026-10-28T14:00:41Z" }
    ],
    "error": null,
    "resources": [
      { "resource_type": "application", "resource_id": "9d2c7e41-60fa-4b13-8e75-c1a4b3f08d26", "service_id": "app", "name": "my-discord-bot" }
    ],
    "stack_id": null,
    "application_id": "9d2c7e41-60fa-4b13-8e75-c1a4b3f08d26",
    "outputs": [
      {
        "label": { "pt-br": "Próximo passo", "en": "Next step" },
        "value": { "en": "Invite the bot to your server and type /ping." },
        "secret": false,
        "once": false
      }
    ],
    "created_at": "2026-10-28T14:00:00Z",
    "updated_at": "2026-10-28T14:00:41Z",
    "finished_at": "2026-10-28T14:00:41Z"
  }
}
```

```json Response (failed) theme={null}
{
  "response": {
    "id": "3f6a9c12-7e4b-4d58-a1c0-5b8e2d9f7a63",
    "kind": "deploy",
    "template_id": "7c1d4f0e-3b8a-4d52-9a66-1f0c2e5a9b41",
    "version_id": "e0b7a2c9-5d14-4f8e-8c3a-92d6b1f47a10",
    "version": "1.0.0",
    "status": "failed",
    "current_step": null,
    "steps": [
      { "step": "validate", "status": "done", "started_at": "2026-10-28T14:00:01Z", "finished_at": "2026-10-28T14:00:02Z" },
      { "step": "apps", "status": "failed", "started_at": "2026-10-28T14:00:02Z", "finished_at": "2026-10-28T14:00:50Z" },
      { "step": "variables", "status": "pending", "started_at": null, "finished_at": null }
    ],
    "error": {
      "code": "BUILD_FAILED",
      "message": "An application of the template failed to build.",
      "step": "apps"
    },
    "resources": [],
    "stack_id": null,
    "application_id": null,
    "outputs": [],
    "created_at": "2026-10-28T14:00:00Z",
    "updated_at": "2026-10-28T14:01:05Z",
    "finished_at": "2026-10-28T14:01:05Z"
  }
}
```

### Error Responses

**code** `string`

The error code indicating the reason for the failure. Possible values:

* `VALIDATION_ERROR`: `deploy_id` is not a valid ID (`400`).
* `API_KEY_SCOPE_DENIED`: The API key does not have the `templates:deploy` scope (`403`).
* `TEMPLATE_DEPLOY_NOT_FOUND`: The job does not exist or belongs to another account (`404`).
* `RATE_LIMIT_EXCEEDED`: Too many requests (`429`).
* `INTERNAL_SERVER_ERROR`: Unexpected failure (`500`).

```json Error Response theme={null}
{
  "code": "TEMPLATE_DEPLOY_NOT_FOUND"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.