> ## 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.

# Obtener trabajo de despliegue de plantilla

> Devuelve el estado de un trabajo de despliegue o actualización de plantilla: pasos, recursos creados, error si falló y salidas al terminar.

Devuelve un trabajo de despliegue o de actualización iniciado por [Desplegar plantilla](https://docs.vertracloud.app/es-es/api-reference/endpoint/templates/deploy.md) o [Actualizar desde plantilla](https://docs.vertracloud.app/es-es/api-reference/endpoint/templates/update.md). Con una clave de API, el ámbito es `templates:deploy`. Solo la cuenta que inició el trabajo puede leerlo; cualquier otro ID de trabajo responde `TEMPLATE_DEPLOY_NOT_FOUND`. La respuesta nunca se guarda en caché. Para ver el progreso en vivo sin hacer polling, usa el [flujo de eventos](https://docs.vertracloud.app/es-es/api-reference/endpoint/templates/deploy-events.md).

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

El ID del trabajo, devuelto cuando el despliegue o la actualización fue aceptado.

### Respuesta

**response** `object`

El trabajo.

**Mostrar objeto**

**id** `string`

El ID del trabajo.

**kind** `string`

`deploy` cuando el trabajo creó recursos a partir de una plantilla; `update` cuando movió recursos existentes a una versión más nueva.

**template\_id** `string`

El ID de la plantilla.

**version\_id** `string`

El ID de la versión que se despliega.

**version** `string`

El número de la versión que se despliega.

**status** `string`

`queued`, `running`, `undoing` (un paso falló y se está eliminando lo que creó el trabajo), `succeeded` o `failed`. Un trabajo `failed` ya deshizo todo lo que creó. `succeeded` y `failed` son estados finales.

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

El paso que se ejecuta ahora, o `null` cuando el trabajo está en cola o ya terminó.

**steps** `object[]`

Los pasos que aplican al trabajo, en orden de ejecución. Cada uno tiene `step`, `status`, `started_at` y `finished_at` (`null` hasta que ocurren). Un paso es `pending`, `running`, `done`, `skipped` (no aplica, por ejemplo cuando no hay base de datos) o `failed`. Pasos: `validate`, `snapshot` (solo en actualizaciones: un snapshot de seguridad antes de cambiar nada), `network`, `databases`, `blob`, `images`, `apps`, `variables`, `certificates`, `start`, `healthcheck`, `outputs` y `rollback` (solo en actualizaciones, cuando una actualización fallida vuelve al snapshot).

**error** `object | null`

Se define cuando `status` es `failed`.

**Mostrar objeto**

**code** `string`

Un código de error, como `TEMPLATE_DEPLOY_FAILED`, `BUILD_FAILED`, `MAX_APPS_REACHED` o `TEMPLATE_PLAN_REQUIRED`.

**message** `string`

Una frase fija y legible, en inglés. Nunca incluye valores de tus variables.

**step** `string | null`

El paso que falló.

**details** `object`

Contexto opcional. En una actualización que no pudo volver al snapshot contiene `rollback_failed`.

**resources** `object[]`

Lo que creó el trabajo, en orden. Cada uno tiene `resource_type`, `resource_id`, `service_id` (el servicio del manifiesto; `null` para el stack y las imágenes) y `name`. Queda vacío tras un fallo, porque el trabajo deshace lo que creó.

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

El stack, cuando la plantilla tiene dos o más servicios.

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

La aplicación, cuando la plantilla tiene una sola aplicación.

**outputs** `object[]`

Las salidas de un trabajo terminado con éxito; vacío antes de eso.

**Mostrar objeto**

**label** `object`

La etiqueta en los tres idiomas.

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

El valor: un texto, o un texto por idioma. En una salida con `once`, el valor se devuelve **solo en la primera lectura** del trabajo terminado y después es `null`.

**secret** `boolean`

`true` cuando el valor es un secreto.

**once** `boolean`

`true` cuando el valor se muestra una sola vez.

**created\_at** `string`

Cuándo se aceptó el trabajo.

**updated\_at** `string`

Cuándo cambió el trabajo por última vez.

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

Cuándo terminó el trabajo, o `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"
  }
}
```

### Respuestas de error

**code** `string`

El código de error que indica el motivo del fallo. Valores posibles:

* `VALIDATION_ERROR`: `deploy_id` no es un ID válido (`400`).
* `API_KEY_SCOPE_DENIED`: La clave de API no tiene el ámbito `templates:deploy` (`403`).
* `TEMPLATE_DEPLOY_NOT_FOUND`: El trabajo no existe o pertenece a otra cuenta (`404`).
* `RATE_LIMIT_EXCEEDED`: Demasiadas peticiones (`429`).
* `INTERNAL_SERVER_ERROR`: Fallo inesperado (`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.