# Retrieve list of Assemblies Lists Assemblies for the authenticated Workspace. `GET` `https://api2.transloadit.com/assemblies` Retrieves a list of Assemblies for your account. They are sorted by creation date descending. ## Request example Run this request in a server-side shell with `curl` and a suitable [bearer token](/docs/api/token-post.md) in `TRANSLOADIT_TOKEN`. If you need a token, expand the setup below. **Need a bearer token?** In a trusted server-side shell with `curl` and `jq`, set `TRANSLOADIT_KEY` and `TRANSLOADIT_SECRET` to your Auth Key and Auth Secret. Keep both credentials and the resulting token secret; never run this setup in browser code. First, create a token with this endpoint’s required scopes. Your Auth Key must already grant those scopes. ```bash if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \ --request POST \ --url 'https://api2.transloadit.com/token' \ --user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'aud=api2' \ --data-urlencode 'scope=assemblies:read')"; then printf '%s\n' "$TOKEN_RESPONSE" >&2 exit 1 fi TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" | jq -er '.access_token | strings | select(length > 0)')" || exit 1 ``` Keep this shell open and run the request below. Reuse the token while it remains valid. ```bash curl --fail-with-body -sS --request GET --get \ --url "https://api2.transloadit.com/assemblies" \ --header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \ --data-urlencode 'params={}' ``` ## Authentication This endpoint accepts signed `params` or a bearer token. See [Authentication](/docs/api/authentication.md) for setup instructions. Required scope for the Auth Key or bearer token: `assemblies:read`. Signed requests require both a `signature` and a future `params.auth.expires` timestamp. Bearer tokens do not require either. ## Query parameters * `params` (JSON string). A JSON-encoded object whose supported keys are listed below. * `signature` (string). Required for signed requests. Omit this field when using a bearer token. ## Supported keys inside the signed `params` field Authentication fields in this list apply to signed requests. With a bearer token, you can omit `params.auth` and the separate `signature` field. Compare the authentication-specific request parameters below. [Complete JSON Schema](/api-reference/schemas/assemblies-get/params-fields.json) `params`: Only the fields listed for this object are accepted. ### `params.assembly_id` `string` Restricts results to one Assembly ID. Validation pattern (regular expression): `^[a-z0-9]{32}$` ### `params.auth` (required for signed requests; optional with a bearer token) [`object`](#params-fields-auth-expires) Contains the Transloadit API key and signature-authentication metadata for an Assembly list request. `params.auth`: Only the fields listed for this object are accepted. #### `params.auth.expires` (required) `string` ISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. #### `params.auth.key` (required) `string` Transloadit API key used to authenticate requests ### `params.fromdate` `string` Specifies the minimum Assembly UTC creation date/time. Only Assemblies after this time are returned. Use the format `Y-m-d H:i:s`. Defaults to seven days before the request. Exact Assembly ID lookups have no default lower bound. ### `params.keywords` `string | Array` Specifies one search expression directly or as a string array whose items are joined with commas. Nonblank rendered expressions must contain at least three characters after trimming. It matches an Assembly ID or six-character ID prefix, a recognized error code, or (when Assembly field search is enabled for the Workspace) an exact custom field name or value. If a recognized error code also matches a custom field name or value, only Assemblies matching both are returned. Defaults to no keyword filter. **Any of the following schemas may apply:** * `string` [Validation pattern (regular expression)](/api-reference/schemas/assemblies-get/params-fields.json) * `Array` * **Array item schema** `string` ### `params.nonce` `string | integer` Unique, random value included in signed request params to make each signature unique and prevent accidental signature reuse. ### `params.order` `"asc" | "desc"` Specifies the sort direction. Defaults to `desc`. ### `params.page` `integer` (default: 1, minimum: 1, maximum: 9007199254740991) Specifies the current page within the current pagination. Defaults to `1`. The derived offset `(page - 1) * pagesize` must remain a safe integer. ### `params.pagesize` `integer` (default: 50, minimum: 1, maximum: 5000) Specifies how many Assemblies to return per API request. Defaults to `50`. ### `params.region` `string` Restricts results to a region. Omission, a whitespace-only value, or `all` includes every region. **Any of the following schemas may apply:** * **Variant 1** `string` [Validation pattern (regular expression)](/api-reference/schemas/assemblies-get/params-fields.json) * **Variant 2** `string` [Validation pattern (regular expression)](/api-reference/schemas/assemblies-get/params-fields.json) ### `params.sort` `"created" | "created_ts" | "updated"` Specifies the field used to sort results. Defaults to `created_ts`. ### `params.template_id` `string` Restricts results to a Template ID or name. Use `no_template` for Assemblies without a Template. Omission or `all` includes every Template. ### `params.todate` `string` Specifies the maximum Assembly UTC creation date/time. Only Assemblies before this time are returned. Use the format `Y-m-d H:i:s`. ### `params.type` `string` Specifies the types of Assemblies to retrieve. Defaults to `all`. Allowed values (10) * `"all"` * `"canceled"` * `"completed"` * `"executing"` * `"expired"` * `"failed"` * `"fixable"` * `"problematic"` * `"request_aborted"` * `"uploading"` ## Request parameters by authentication method ### With signed params Include your Auth Key as `params.auth.key`. When signing the request, include a future `params.auth.expires` timestamp and send the signature in the separate `signature` field. The field definitions below use paths inside `params`. [Complete JSON Schema](/api-reference/schemas/assemblies-get/signed-params.json) `params`: Only the fields listed for this object are accepted. Uses the field definitions above: [`params.assembly_id`](#params-fields-assembly_id), [`params.auth`](#params-fields-auth), [`params.fromdate`](#params-fields-fromdate), [`params.keywords`](#params-fields-keywords), [`params.nonce`](#params-fields-nonce), [`params.order`](#params-fields-order), [`params.page`](#params-fields-page), [`params.pagesize`](#params-fields-pagesize), [`params.region`](#params-fields-region), [`params.sort`](#params-fields-sort), [`params.template_id`](#params-fields-template_id), [`params.todate`](#params-fields-todate), [`params.type`](#params-fields-type) ### With a bearer token Send the bearer token in the `Authorization` header. You can omit `params.auth` and the separate `signature` field. Other required parameters still apply. The field definitions below use paths inside `params`. [Complete JSON Schema](/api-reference/schemas/assemblies-get/bearer-params.json) `params`: Only the fields listed for this object are accepted. Uses the field definitions above: [`params.assembly_id`](#params-fields-assembly_id), [`params.fromdate`](#params-fields-fromdate), [`params.keywords`](#params-fields-keywords), [`params.nonce`](#params-fields-nonce), [`params.order`](#params-fields-order), [`params.page`](#params-fields-page), [`params.pagesize`](#params-fields-pagesize), [`params.region`](#params-fields-region), [`params.sort`](#params-fields-sort), [`params.template_id`](#params-fields-template_id), [`params.todate`](#params-fields-todate), [`params.type`](#params-fields-type) #### `params.auth` [`object`](#bearer-params-auth-expires) Contains the Transloadit API key and signature-authentication metadata for an Assembly list request. `params.auth`: Only the fields listed for this object are accepted. ##### `params.auth.expires` `string` ISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. ##### `params.auth.key` `string` Transloadit API key used to authenticate requests ## Response Here’s an example response body: ```jsonc { "count": 50, "items": [ { "account_id": "7c91e50845204dea9ed4791f7d8440f1", "created": "2023-02-11T16:04:22.000Z", "created_ts": 1676131462, "error": null, "execution_duration": 2.337, "execution_start": "2023-02-11T16:04:24.000Z", "files": "[\"Saturn as seen from the Cas....jpg\"]", "id": "195c60855fda4fb9a3b2f848374ca4e1", "instance": "tam.transloadit.com", "notify_url": null, "ok": "ASSEMBLY_COMPLETED", "parent_id": null, "redirect_url": null, "region": "eu-west-1", "template_id": "40b0efc6b37f432dbe9485017b52a7b7", "template_name": "my-template-1676131432311", "warning_count": 0 }, { "account_id": "7c91e50845204dea9ed4791f7d8440f1", "created": "2023-02-11T16:04:04.000Z", "created_ts": 1676131444, "error": null, "execution_duration": 6.275, "execution_start": "2023-02-11T16:04:06.000Z", "files": "[\"green grass fiels.jpg\",\"Morning Dew.jpg\",\"green leaf plant.jpg\"]", "id": "72fc13f46db84fa1969d913ca8763de1", "instance": "tam.transloadit.com", "notify_url": null, "ok": "ASSEMBLY_COMPLETED", "parent_id": null, "redirect_url": null, "region": "eu-west-1", "template_id": "40b0efc6b37f432dbe9485017b52a7b7", "template_name": "my-template-1676131432311", "warning_count": 0 } ] } ``` ### 2xx success JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/assemblies-get/response-1-body.json) The response may contain additional fields. ##### `count` (required) `integer` (minimum: 0) ##### `items` (required) `Array` **Array item schema** [`object`](#response-1-body-items-items-1-account_id) `items[]`: The response may contain additional fields. ###### `items[].account_id` `null | string` ###### `items[].bytes_expected` `number` The number of bytes that this *Assembly* expects to be uploaded. ###### `items[].bytes_received` `number` The number of bytes that have been uploaded to this *Assembly* so far. This is primarily used by clients to display upload progress. ###### `items[].bytes_usage` `number | null` ###### `items[].created` (required) `string` ###### `items[].created_ts` `number` ###### `items[].error` `null | string` ###### `items[].execution_duration` `number | null` The time taken by Transloadit to execute this *Assembly*, in seconds. ###### `items[].execution_start` `null | string` ###### `items[].files` `null | string` ###### `items[].id` (required) `string` ###### `items[].instance` `null | string` ###### `items[].notify_url` `null | string` ###### `items[].num_input_files` `number | null` ###### `items[].ok` `null | string` ###### `items[].parent_id` `null | string` ###### `items[].redirect_url` `null | string` ###### `items[].region` `null | string` ###### `items[].template_id` `null | string` ###### `items[].template_name` `null | string` ###### `items[].upload_duration` `number` The time taken by the uploader to upload files, in seconds. ###### `items[].warning_count` `number | null` ### Error response JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/assemblies-get/response-2-body.json) At least one of these properties is required: error, message, reason The response may contain additional fields. ##### `assembly_id` `string` ##### `error` `string` (minimum length: 1) ##### `http_code` `number | string` * `number` * `string` [Validation pattern (regular expression)](/api-reference/schemas/assemblies-get/response-2-body.json) ##### `message` `string` Human-readable explanation of the error. Its wording can vary; use the `error` code when handling a specific failure. ##### `reason` `null | string | number | boolean | Array | object` **Any of the following schemas may apply:** * `null` * `string` * `number` * `boolean` * `Array` * **Array item schema** `any value` * `object` * **Additional property schema** `any value` ### HTTP 400 JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/assemblies-get/response-3-body.json) **Named errors and the general error format** * **error: "ASSEMBLY\_LIST\_ERROR"** Bad parameters. The response may contain additional fields. * **`error` (required)** `string` (always: "ASSEMBLY\_LIST\_ERROR") * **`http_code`** `number` (always: 400) * **`message`** `string` Human-readable explanation of the error. Its wording can vary; use the `error` code when handling a specific failure. * **General error format** [See the general error response fields.](#response-2-body)