# Stream Assembly changes live

GET`{UPDATE_STREAM_URL}`

In the response after creating an Assembly you will find two fields for retrieving theAssembly Status: `assembly_ssl_url` and `update_stream_url`. You can[fetch the current Assembly Status](/docs/api/assemblies-assembly-id-get.md) from the URL provided in`assembly_ssl_url`. To obtain information about how the Assembly is progressing, you can either poll that regularly, or subscribe to the update stream, which is described in this document.

## Server-Sent Events

The `update_stream_url` property in the Assembly Status defines a URL, where the update stream for the corresponding Assembly is available using server-sent events.

[Server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent%5Fevents/Using%5Fserver-sent%5Fevents)are a web technology for sending live notifications from the server to a client over HTTP. It is similar to Web Sockets, but only allows unidirectional messages from the server to the client and consists of a[simple, text-based format](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent%5Fevents/Using%5Fserver-sent%5Fevents#event%5Fstream%5Fformat).

While the Assembly is either in the uploading or executing state, a client can connect to this endpoint by sending a `GET` request with the `Accept: text/event-stream` header field to the URL specified in `update_stream_url` and parse the response stream. The server can send a mixture of messages and events to the client. The difference between them is that events include an additional payload with information, while messages don't.

## Messages

A message consists of the message name and no additional payload. On the wire, a message with the name `assembly_finished` looks like this (`[NL]` indicates a new line):

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```
data: assembly_finished[NL]
[NL]

```

Transloadit sends the following messages:

* `assembly_upload_meta_data_extracted` is emitted when all uploads are finished and the meta data has been extracted for all of them.
* `assembly_uploading_finished` is emitted when all uploads for this Assembly have been finished and the Assembly transitions from the uploading into the executing state.
* `assembly_finished` is emitted when the Assembly is complete and all files have been processed. The server will end the stream after this message.
* `ping` is emitted periodically to keep the connection alive while the Assembly is being processed. It is currently sent every minute, although this interval might change in the future.

## Events

An event consists of the event name and an additional payload. On the wire, an event with the name`assembly_result_finished` looks like this (`[NL]` indicates a new line):

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```
event: assembly_result_finished[NL]
data: {"id":"6bb16f6cd49a44b4ae431f576e016c6d","name":"lesereihe.doc",...}[NL]
[NL]

```

Transloadit sends the following events:

* `assembly_error` is emitted when an error occurs while the Assembly is executing. The server will end the stream after this event. Additional information about the error is included, for example:\
  ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```json
{  
  "error": "DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION",  
  "http_code": 400,  
  "step": "avatar",  
  "previousStep": ":original",  
  "worker": "dhor.transloadit.com",  
  "msg": "The output format pdf is not supported for the input format pdf. The input format pdf is currently not allowed."  
}  
```

* `assembly_upload_finished` is emitted for each upload that is finished. Additional information about the uploaded file is included. The structure is the same as an object in the `uploads` array from the [Assembly Status](/docs/api/assembly-status-response.md), for example:\
  ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```jsonc
{  
  "id": "6bb16f6cd49a44b4ae431f576e016c6d",  
  "name": "lesereihe.doc",  
  "basename": "lesereihe",  
  "ext": "doc",  
  "size": 61440,  
  "mime": "application/msword",  
  "type": null,  
  "field": "file",  
  "md5hash": "154a9349b8f9111865a07ed0a7050f55",  
  // …  
}  
```

* `assembly_result_finished` is emitted whenever a new result from a Step is available. The step name and additional information about the result are included. The structure is the same as an object in the `results` array from the[Assembly Status](/docs/api/assembly-status-response.md), for example:\
  ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```jsonc
[  
  "avatar",  
  {  
    "id": "5789e06b48ad450aa55f9b3721376581",  
    "name": "lesereihe.pdf",  
    "basename": "lesereihe",  
    "ext": "pdf",  
    "size": 120456,  
    "mime": "application/pdf",  
    "type": "pdf",  
    "field": "file",  
    "md5hash": "e9df77e5ee87e8ec3b4453bcddf191bc",  
    "meta": {  
      "page_count": 1,  
      "width": 1238,  
      "height": 1750,  
      // …  
    },  
    // …  
  }  
]  
```

* `assembly_execution_progress` is emitted at regular intervals with information about the overallExecution Progress of the Assembly and its files. The structure and mechanisms are detailed in[Assembly Execution Progress](/docs/topics/assembly-execution-progress.md), for example:\
  ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```json
{  
  "progress_combined": 50,  
  "progress_per_original_file": [  
    {  
      "original_id": "6bb16f6cd49a44b4ae431f576e016c6d",  
      "progress": 50  
    }  
  ]  
}  
```

Note: `progress_per_original_file` is keyed by `original_id`. Imported files without an`original_id` won’t appear in this list.

###### Note

Additional messages and events might be added in the future. A client should therefore ignore unexpected messages/events and not error out.

## Example in JavaScript

Modern browsers provide native support for server-sent events via the `EventSource` constructor. Assuming that the Assembly Status is stored in the `assembly_status` variable, the client can listen for the `assembly_finished` message, the `assembly_uploading_finished` message, and the`assembly_result_finished` event as follows:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```js
const stream = new EventSource(assembly_status.update_stream_url)

// Listen for the assembly_finished and assembly_uploading_finished messages
stream.addEventListener('message', (event) => {
  switch (event.data) {
    case 'assembly_finished':
      console.log('Assembly is finished')
      break
    case 'assembly_uploading_finished':
      console.log('All uploads are finished')
      break
  }
})

// Listen for the assembly_result_finished event
stream.addEventListener('assembly_result_finished', (event) => {
  const result = JSON.parse(event.data)
  console.log('Assembly result is available', result)
})

```

## GET query components

No request query components needed

## Response

Here’s an example response body:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```
data: assembly_uploading_finished

event: assembly_upload_finished
data: {"id":"7354d54e9dfa4a47b0f8c451730038b9","name":"lesereihe.doc","basename":"lesereihe","ext":"doc","size":61440,"mime":"application/msword","type":null,"field":"file","md5hash":"154a9349b8f9111865a07ed0a7050f55", [...]

data: assembly_upload_meta_data_extracted

event: assembly_result_finished
data: ["avatar",{"id":"77d73782d83447c38a87af024e03d329","name":"lesereihe.pdf","basename":"lesereihe","ext":"pdf","size":120456,"mime":"application/pdf","type":"pdf","field":"file","md5hash":"278042dc10ac7a9b583c9467dac8cfda", [...]

event: assembly_execution_progress
data: {"progress_combined":100,"progress_per_original_file":[]}

data: assembly_finished

```

For more information about the response format, please refer to Mozilla's documentation about[server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent%5Fevents/Using%5Fserver-sent%5Fevents#event%5Fstream%5Fformat).