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

Assembly Execution Progress is still experimental. 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 about 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

  • Pair upload progress with execution progress so users see the entire pipeline.
  • Show per-file progress in batch uploads to avoid “stuck” impressions.
  • Use combined progress for a single overall bar and per-file progress for a detailed list view.

Caveats to know

Some 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 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 deeper walkthrough or code examples, start with the Assembly Execution Progress docs and then wire the stream events into your UI.