When uploads finish, users still want to know what’s happening to their files. Our new Assembly Execution Progress feature fills that gap with real-time, per-file progress events during processing, so your UI can show a meaningful status instead of a simple spinner.

Assembly Execution Progress is still experimental. Its behavior, API details, and pricing may evolve while we continue to refine it. If you run into issues, please contact us.

Why it matters

Upload progress tells users when a file reaches our servers. Assembly Execution Progress tells them what happens next: how far their files have moved through each processing Step. This makes complex pipelines feel trustworthy, especially when different files take different paths.

How it works

Transloadit estimates overall progress by predicting the remaining Steps in your Assembly and combining those estimates with live execution data (for example, encoding progress from /video/encode). You receive a combined percentage plus per-file progress values, updated approximately every two seconds.

Enable it in your Assembly

Add emit_execution_progress: true to your Assembly Instructions when you create the Assembly:

{
  "steps": {
    "resized": {
      "robot": "/image/resize",
      "use": ":original",
      "width": 100,
      "height": 100,
      "resize_strategy": "fillcrop"
    }
  },
  "emit_execution_progress": true
}

Consume the progress stream

Open the Assembly update stream and listen for assembly_execution_progress events. Each event includes a combined percentage and an array of per-file progress values.

{
  "progress_combined": 75,
  "progress_per_original_file": [
    {
      "original_id": "6bb16f6cd49a44b4ae431f576e016c6d",
      "progress": 50
    },
    {
      "original_id": "56921a2dd46246d3b4d3a98b9f8ed4e1",
      "progress": 100
    }
  ]
}

You can find the full stream details in the Assembly update stream documentation and the Assembly Execution Progress topic.

UI tips

:bulb: Pair upload progress with execution progress, so users see the entire pipeline.

:bulb: Show per-file progress in batch uploads to avoid “stuck” impressions.

:bulb: Use combined progress for a single overall bar and per-file progress for a detailed list view.

Caveats to be aware of

Certain Steps have unpredictable result counts (for example, importing directories, extracting archives, or generating document thumbnails without a fixed page list). If your Assembly includes those Steps, execution progress won’t be emitted until they complete. After that, updates resume as normal.

Execution Progress is not available for URL Transform Assemblies (it is ignored even if the flag is set). For multipart uploads, progress only begins once the upload metadata is extracted, so you won’t see execution events until uploads finish. Finally, progress_per_original_file is keyed by original_id, so imported files without an original ID won’t appear in the per-file list.

Next steps

If you want a more thorough walkthrough or code examples, start with the Assembly Execution Progress docs and then wire the stream events into your UI.