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

# Stream Template Deploy Events

> Streams the progress of a template deploy or update job as Server-Sent Events, one event per change of step, until the job ends.

Streams the progress of a deploy or update job so you do not have to poll. With an API key the scope is `templates:deploy`. Only the account that started the job can follow it; any other job ID is `TEMPLATE_DEPLOY_NOT_FOUND`.

The response is a **Server-Sent Events** stream (`text/event-stream`), not JSON. It starts with the current state of the job and then sends a `progress` event every time the job changes. A `heartbeat` event arrives every 15 seconds while nothing changes, to keep the connection open. When the job reaches `succeeded` or `failed`, an `end` event closes the stream. Because the state comes from stored data, you can reconnect at any time and get the current state again.

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

The ID of the job.

### Events

**progress** `event`

The `data` is one JSON object with the state of the job.

**Toggle object**

**deploy\_id** `string`

The job ID.

**status** `string`

`queued`, `running`, `undoing`, `succeeded` or `failed`.

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

The step running now, or `null`.

**steps** `object[]`

The steps of the job with `step`, `status`, `started_at` and `finished_at`, as in [Get Deploy Job](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy-status.md).

**error** `object | null`

The readable error (`code`, `message`, `step`) of a failed job, or `null`.

**heartbeat** `event`

A keep-alive. The `data` is an empty object (`{}`).

**end** `event`

The job is over and the stream closes. The `data` is `{ "deploy_id": "..." }`.

Events never carry outputs, resources or variable values. When you receive `end`, read the job with [Get Deploy Job](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy-status.md) to get the outputs. A secret output marked `once` is returned on that first read of the finished job.

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

```text Response theme={null}
event: progress
data: {"deploy_id":"3f6a9c12-7e4b-4d58-a1c0-5b8e2d9f7a63","status":"running","current_step":"apps","steps":[{"step":"validate","status":"done","started_at":"2026-10-28T14:00:01Z","finished_at":"2026-10-28T14:00:02Z"},{"step":"apps","status":"running","started_at":"2026-10-28T14:00:02Z","finished_at":null},{"step":"start","status":"pending","started_at":null,"finished_at":null}],"error":null}

event: heartbeat
data: {}

event: progress
data: {"deploy_id":"3f6a9c12-7e4b-4d58-a1c0-5b8e2d9f7a63","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":"start","status":"done","started_at":"2026-10-28T14:00:21Z","finished_at":"2026-10-28T14:00:30Z"}],"error":null}

event: end
data: {"deploy_id":"3f6a9c12-7e4b-4d58-a1c0-5b8e2d9f7a63"}
```

### Error Responses

Errors are returned before the stream opens, as JSON.

**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`).
* `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.