Transloadit uses a single response format for creating and querying Assemblies, appending responses to upload forms, and sending Notifications.

The following is a full example of a Transloadit response. Since files are processed in parallel, the ordering for results does not necessarily follow the same order as uploads. There could also be multiple results for a single upload. To match results with uploads, you can use the original_id field, which is present in both items.

Example response

{
  "assembly_id": "7828446e5acd4aa996dce3455ec914e9",
  "ok": "ASSEMBLY_COMPLETED",
  "message": "The Assembly was successfully completed.",
  "warnings": [],
  "account_id": "4ce4fb3d9d1842b6ba5d6f3ccee4b066",
  "assembly_ssl_url": "https://api2-morven.transloadit.com/assemblies/7828446e5acd4aa996dce3455ec914e9",
  "assembly_url": "http://api2-morven.transloadit.com/assemblies/7828446e5acd4aa996dce3455ec914e9",
  "build_id": "339",
  "bytes_expected": 486608,
  "bytes_received": 486608,
  "bytes_usage": 1097155,
  "client_agent": null,
  "client_ip": null,
  "client_referer": null,
  "companion_url": "https://api2-morven.transloadit.com/companion/",
  "executing_jobs": [],
  "execution_duration": 5.281,
  "execution_start": "2020/01/09 12:02:08 GMT",
  "expected_tus_uploads": 1,
  "fields": {},
  "finished_tus_uploads": 1,
  "has_dupe_jobs": false,
  "instance": "morven.transloadit.com",
  "is_infinite": false,
  "jobs_queue_duration": 0.01,
  "last_job_completed": "2020/01/09 12:02:14 GMT",
  "merged_params": "{\"steps\":{\":original\":{\"robot\":\"/upload/handle\"},\"faces_detected\":{\"use\":\":original\",\"robot\":\"/image/facedetect\",\"crop\":true,\"faces\":\"max-confidence\",\"format\":\"preserve\",\"crop_padding\":\"10%\"},\"exported\":{\"use\":[\"faces_detected\",\":original\"],\"robot\":\"/s3/store\",\"credentials\":\"demo_s3_credentials\"}},\"auth\":{\"key\":\"****\",\"expires\":\"2020-01-10T12:02:05.826Z\"}}",
  "notify_duration": null,
  "notify_response_code": null,
  "notify_start": null,
  "notify_status": null,
  "notify_url": null,
  "params": "{\"steps\":{\":original\":{\"robot\":\"/upload/handle\"},\"faces_detected\":{\"use\":\":original\",\"robot\":\"/image/facedetect\",\"crop\":true,\"faces\":\"max-confidence\",\"format\":\"preserve\",\"crop_padding\":\"10%\"},\"exported\":{\"use\":[\"faces_detected\",\":original\"],\"robot\":\"/s3/store\",\"credentials\":\"demo_s3_credentials\"}},\"auth\":{\"key\":\"****\",\"expires\":\"2020-01-10T12:02:05.826Z\"}}",
  "parent_assembly_status": null,
  "parent_id": null,
  "queue_duration": 0.184,
  "running_jobs": [],
  "start_date": "2020/01/09 12:02:06 GMT",
  "started_jobs": [
    ":original:::original",
    "faces_detected:::original",
    "exported:::original",
    "exported::faces_detected"
  ],
  "started_tus_uploads": 1,
  "template": null,
  "template_id": null,
  "transloadit_client": "node-sdk:2.0.8",
  "tus_url": "https://api2-morven.transloadit.com/resumable/files/",
  "upload_duration": 2.814,
  "upload_meta_data_extracted": true,
  "uppyserver_url": "https://api2-morven.transloadit.com/companion/",
  "update_stream_url": "https://api2-morven.transloadit.com/ws20074?assembly=7828446e5acd4aa996dce3455ec914e9",
  "websocket_url": "https://api2-morven.transloadit.com/ws20074",
  "uploads": [
    {
      "id": "a30bd0776e7f4ac3817b056d102e8219",
      "basename": "joe-gardner-149699",
      "ext": "jpg",
      "field": "file",
      "from_batch_import": false,
      "is_tus_file": true,
      "md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
      "mime": "image/jpeg",
      "name": "joe-gardner-149699.jpg",
      "original_basename": "joe-gardner-149699",
      "original_id": "a30bd0776e7f4ac3817b056d102e8219",
      "original_md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
      "original_name": "joe-gardner-149699.jpg",
      "original_path": "/",
      "size": 485784,
      "ssl_url": "https://s3.amazonaws.com/demos.transloadit.com/a3/0bd0776e7f4ac3817b056d102e8219/joe-gardner-149699.jpg",
      "tus_upload_url": "https://api2-morven.transloadit.com/resumable/files/UPLOAD_ID+CAPABILITY_TOKEN",
      "type": "image",
      "url": "http://demos.transloadit.com.s3.amazonaws.com/a3/0bd0776e7f4ac3817b056d102e8219/joe-gardner-149699.jpg",
      "meta": {
        "aspect_ratio": "1.500",
        "average_color": "#b09d96",
        "colorspace": "RGB",
        "date_file_modified": "2020/01/09 12:02:08 GMT",
        "frame_count": 1,
        "has_clipping_path": false,
        "has_transparency": false,
        "height": 1667,
        "width": 2500
      }
    }
  ],
  "results": {
    ":original": [
      {
        "id": "a30bd0776e7f4ac3817b056d102e8219",
        "basename": "joe-gardner-149699",
        "cost": 97157,
        "execTime": 0.81,
        "ext": "jpg",
        "field": "file",
        "from_batch_import": false,
        "is_tus_file": false,
        "md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
        "mime": "image/jpeg",
        "name": "joe-gardner-149699.jpg",
        "original_basename": "joe-gardner-149699",
        "original_id": "a30bd0776e7f4ac3817b056d102e8219",
        "original_md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
        "original_name": "joe-gardner-149699.jpg",
        "original_path": "/",
        "queue": "live",
        "queueTime": 0.01,
        "size": 485784,
        "ssl_url": "https://s3.amazonaws.com/demos.transloadit.com/a3/0bd0776e7f4ac3817b056d102e8219/joe-gardner-149699.jpg",
        "tus_upload_url": null,
        "type": "image",
        "url": "http://demos.transloadit.com.s3.amazonaws.com/a3/0bd0776e7f4ac3817b056d102e8219/joe-gardner-149699.jpg",
        "meta": {
          "aspect_ratio": "1.500",
          "average_color": "#b09d96",
          "colorspace": "RGB",
          "date_file_modified": "2020/01/09 12:02:08 GMT",
          "frame_count": 1,
          "has_clipping_path": false,
          "has_transparency": false,
          "height": 1667,
          "width": 2500
        }
      }
    ],
    "faces_detected": [
      {
        "id": "b8d12f6c517541ca86bf50c537cedb27",
        "basename": "joe-gardner-149699",
        "cost": 627606,
        "execTime": 0.83,
        "ext": "jpg",
        "field": "file",
        "from_batch_import": false,
        "is_tus_file": false,
        "md5hash": "2a5cd917f4281b9438956e489c63dfd2",
        "mime": "image/jpeg",
        "name": "joe-gardner-149699.jpg",
        "original_basename": "joe-gardner-149699",
        "original_id": "a30bd0776e7f4ac3817b056d102e8219",
        "original_md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
        "original_name": "joe-gardner-149699.jpg",
        "original_path": "/",
        "queue": "live",
        "queueTime": 0,
        "size": 141822,
        "ssl_url": "https://s3.amazonaws.com/demos.transloadit.com/b8/d12f6c517541ca86bf50c537cedb27/joe-gardner-149699.jpg",
        "tus_upload_url": null,
        "type": "image",
        "url": "http://demos.transloadit.com.s3.amazonaws.com/b8/d12f6c517541ca86bf50c537cedb27/joe-gardner-149699.jpg",
        "meta": {
          "aspect_ratio": "0.739",
          "average_color": "#8d654d",
          "colorspace": "RGB",
          "date_file_created": "2020/01/09 12:02:09 GMT",
          "date_file_modified": "2020/01/09 12:02:12 GMT",
          "faces": [
            {
              "confidence": 99.99,
              "height": 840,
              "width": 621,
              "x1": 981,
              "x2": 1550,
              "y1": 121,
              "y2": 891
            }
          ],
          "frame_count": 1,
          "has_clipping_path": false,
          "has_transparency": false,
          "height": 840,
          "width": 621
        }
      }
    ]
  }
}

Explanation of fields

ok: Indicates a non-error lifecycle status, including uploading, executing, aborted, and canceled states. Successful processing is indicated by ASSEMBLY_COMPLETED. If the Assembly encountered an error, the error key below is used instead of this key.
error: Indicates an error status. This key is only present if the Assembly failed.
message: A human-readable message explaining the state of this Assembly. This is not always present.
assembly_id: The unique ID of this Assembly. You can store this in a database when an Assembly is created, and use it to match incoming Notifications.
assembly_url: The unique URL used to query the current status of this Assembly.
assembly_ssl_url: The unique URL used to query the current status of this Assembly, but ready to be used over SSL/HTTPS. All API requests that are sent to the assembly_url can also be sent to the assembly_ssl_url.
companion_url: The URL to the Companion server that this Assembly may communicate with.
websocket_url: The URL to a Websocket (uses Socket.IO) server from which you can get realtime status updates of this Assembly.
update_stream_url: The URL to a server-sent events stream from which you can get realtime status updates of this Assembly.
tus_url: The URL to the tus server used by this Assembly for resumable uploads.
bytes_received: The number of bytes that have been uploaded to this Assembly so far. This is primarily used by clients to display upload progress.
bytes_expected: The number of bytes that this Assembly expects to be uploaded.
bytes_usage: The total number of bytes that this Assembly processed that count towards your usage bill. The sum of bytes_usage of all of your Assemblies equal your total monthly usage.
client_agent: The uploader’s user agent is not exposed; this deprecated field is always null.
client_ip: The uploader’s IP address is not exposed; this deprecated field is always null.
client_referer: The uploader’s referrer URL is not exposed; this deprecated field is always null.
start_date: The date and time at which upload started for this Assembly.
upload_duration: The time taken by the uploader to upload files, in seconds.
execution_duration: The time taken by Transloadit to execute this Assembly, in seconds.
fields: A key/value map of additional form fields for integrations that cannot use <form> encapsulation, such as Uppy.
uploads: An array of files uploaded for this Assembly. For more information, see the metadata docs.
results: The result files that Transloadit has produced so far. Each key is the name of the Step that produced a file. Storage Robots do not produce files, so their Step names are omitted. When an error occurs, this object may contain partial results.

Custom file metadata

File objects in uploads and results can contain a user_meta object with custom JSON values, including nested objects and arrays. Treat it as optional when reading responses; it can be empty ({}).

The map contains values from tus uploads, Step instructions, and any metadata inherited by the Robot. Values set by the current Step replace matching top-level keys. This is separate from detected file metadata in meta and Assembly-level request values in fields.

For example, a file can contain "user_meta": { "stage": "resized", "approved": false }. Downstream Steps read ${file.user_meta.stage} and ${file.user_meta.approved}. See Custom metadata for evaluation timing, inheritance rules, and a complete workflow.

Assembly Status response

Example response

Explanation of fields

Custom file metadata