> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/cloudconvert.md).

# CloudConvert

Convert, merge, and optimize files with CloudConvert. Converted files are served from temporary public links that expire 24 hours after creation.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector              | Authentication |
| ---------------------- | -------------- |
| CloudConvert (API Key) | API Key        |

#### CloudConvert (API Key)

Convert, merge, and optimize files with CloudConvert. Converted files are served from temporary public links that expire 24 hours after creation, so download or forward them before then.

**Set up in CloudConvert**

1. Prepare the CloudConvert account or service that the workflow will access. Grant access to the required resources and operations.
2. **API Key:** Create an API key at CloudConvert with the task.read, task.write, user.read, webhook.read, and webhook.write scopes. Converted files are served from temporary public links that expire 24 hours after creation, so download or forward them before then.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **CloudConvert (API Key)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                                                                                                                                                                      |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key       | Yes      | Create an API key at CloudConvert with the task.read, task.write, user.read, webhook.read, and webhook.write scopes. Converted files are served from temporary public links that expire 24 hours after creation, so download or forward them before then. [Provider instructions](https://cloudconvert.com/dashboard/api/v2/keys). |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **CloudConvert** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Convert File

Convert a file from a link into another format, such as DOCX to PDF or PNG to JPG.

**Required permissions:** `task.write`, `task.read`.

**Inputs**

| Field             | Type            | Required | Description                                                                                                                         |
| ----------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| File URL          | string          | Yes      | Link to the file you want to convert. It must be reachable without a login.                                                         |
| Convert To        | select (string) | Yes      | The format you want the file converted into. Options load from the selected connection.                                             |
| Output File Name  | string          | No       | Name for the converted file. Leave blank to keep the original name with the new extension.                                          |
| Source Format     | string          | No       | The current format of the file. Only needed when the link has no file extension.                                                    |
| Wait For The File | boolean         | No       | Wait for the conversion to finish so the download link is ready. Turn off for very large files and check back later. Default: true. |

**Outputs**

| Field         | Type   | Description                                                                  |
| ------------- | ------ | ---------------------------------------------------------------------------- |
| Job ID        | string | Identifier of the CloudConvert job that ran the conversion.                  |
| Status        | string | Whether the conversion finished, is still running, or failed.                |
| Download Link | string | Temporary link to the converted file. Expires 24 hours after the conversion. |
| File Name     | string | Name of the converted file.                                                  |
| Error         | string | Why the conversion failed, when it did.                                      |

#### Merge Files Into PDF

Combine several files into one PDF, in the order you list them.

**Required permissions:** `task.write`, `task.read`.

**Inputs**

| Field             | Type    | Required | Description                                                                             |
| ----------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| File URLs         | string  | Yes      | Links to the files to merge, separated by commas. They appear in the PDF in this order. |
| Output File Name  | string  | No       | Name for the merged PDF.                                                                |
| Wait For The File | boolean | No       | Wait for the merge to finish so the download link is ready. Default: true.              |

**Outputs**

| Field         | Type   | Description                                                         |
| ------------- | ------ | ------------------------------------------------------------------- |
| Job ID        | string | Identifier of the CloudConvert job that ran the merge.              |
| Status        | string | Whether the merge finished, is still running, or failed.            |
| Download Link | string | Temporary link to the merged PDF. Expires 24 hours after the merge. |
| File Name     | string | Name of the merged PDF.                                             |
| Error         | string | Why the merge failed, when it did.                                  |

#### Compress File

Shrink a PDF, PNG, or JPG so it takes up less space, keeping the same format.

**Required permissions:** `task.read`, `task.write`.

**Inputs**

| Field               | Type            | Required | Description                                                                                                                                                                                                                              |
| ------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| File URL            | string          | Yes      | Link to the PDF, PNG, or JPG you want to compress.                                                                                                                                                                                       |
| Compression Profile | select (string) | No       | How aggressively to compress a PDF. 'Web' suits most uses; 'Max' makes the smallest file but may soften quality. Available values: Web (balanced), Print (CMYK), Archive (long-term storage), MRC (scanned images), Max (smallest file). |
| Output File Name    | string          | No       | Name for the compressed file.                                                                                                                                                                                                            |
| Wait For The File   | boolean         | No       | Wait for compression to finish so the download link is ready. Default: true.                                                                                                                                                             |

**Outputs**

| Field         | Type   | Description                                                            |
| ------------- | ------ | ---------------------------------------------------------------------- |
| Job ID        | string | Identifier of the CloudConvert job that ran the compression.           |
| Status        | string | Whether compression finished, is still running, or failed.             |
| Download Link | string | Temporary link to the compressed file. Expires 24 hours after the job. |
| File Name     | string | Name of the compressed file.                                           |
| Error         | string | Why compression failed, when it did.                                   |

#### Import File From URL

Fetch a file from a link and get back a temporary CloudConvert link you can pass to other steps.

**Required permissions:** `task.write`, `task.read`.

**Inputs**

| Field             | Type    | Required | Description                                                           |
| ----------------- | ------- | -------- | --------------------------------------------------------------------- |
| File URL          | string  | Yes      | Link to the file you want to bring into CloudConvert.                 |
| File Name         | string  | No       | Name to give the imported file. Leave blank to take it from the link. |
| Wait For The File | boolean | No       | Wait for the import to finish so the link is ready. Default: true.    |

**Outputs**

| Field             | Type   | Description                                                               |
| ----------------- | ------ | ------------------------------------------------------------------------- |
| Job ID            | string | Identifier of the CloudConvert job that ran the import.                   |
| Status            | string | Whether the import finished, is still running, or failed.                 |
| CloudConvert Link | string | Temporary CloudConvert link to the imported file. Expires after 24 hours. |
| File Name         | string | Name of the imported file.                                                |
| Error             | string | Why the import failed, when it did.                                       |

#### Create Custom Job

Run a custom multi-step CloudConvert job for cases the other actions do not cover, such as adding a watermark or taking a website screenshot.

**Required permissions:** `task.write`, `task.read`.

**Inputs**

| Field            | Type     | Required | Description                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Task Definition  | textarea | Yes      | The job steps as JSON. Each step has a name and an operation, and steps refer to earlier steps by name. Do not put passwords, API keys, or storage credentials in here: this field is saved with the workflow as ordinary configuration, is not encrypted, and its value shows up in run history. To read a private file, use an import/url step with a pre-signed link instead. |
| Tag              | string   | No       | Your own label for this job, useful for finding it later or routing its completion event.                                                                                                                                                                                                                                                                                        |
| Wait For The Job | boolean  | No       | Wait for the job to finish before continuing. Off by default, since custom jobs can run for a long time. Default: false.                                                                                                                                                                                                                                                         |

**Outputs**

| Field         | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Job ID        | string | Identifier of the created job.                                        |
| Status        | string | Whether the job finished, is still running, or failed.                |
| Download Link | string | Temporary link to the first exported file, when the job has finished. |
| File Name     | string | Name of the first exported file, when the job has finished.           |
| Error         | string | Why the job failed, when it did.                                      |

#### Get Job Status

Check whether a conversion job has finished and get its download link.

**Required permissions:** `task.read`.

**Inputs**

| Field            | Type    | Required | Description                                                                                     |
| ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------- |
| Job ID           | string  | Yes      | The job identifier returned when the job was created.                                           |
| Wait For The Job | boolean | No       | Keep checking until the job finishes instead of reporting its status right now. Default: false. |

**Outputs**

| Field         | Type          | Description                                                              |
| ------------- | ------------- | ------------------------------------------------------------------------ |
| Status        | string        | Whether the job finished, is still running, or failed.                   |
| Download Link | string        | Temporary link to the finished file. Expires 24 hours after the job ran. |
| File Name     | string        | Name of the finished file.                                               |
| Tag           | string        | The label set on the job when it was created.                            |
| Error         | string        | Why the job failed, when it did.                                         |
| Steps         | object\_array | The individual steps of this job, each with its own id and status.       |

#### Get Task Status

Check a single step inside a job, to see exactly which step failed and why.

**Required permissions:** `task.read`.

**Inputs**

| Field   | Type   | Required | Description                                |
| ------- | ------ | -------- | ------------------------------------------ |
| Task ID | string | Yes      | The identifier of the individual job step. |

**Outputs**

| Field         | Type   | Description                                                      |
| ------------- | ------ | ---------------------------------------------------------------- |
| Status        | string | Whether this step finished, is still running, or failed.         |
| Operation     | string | What this step does, such as converting or exporting.            |
| Download Link | string | Temporary link to this step's output file, when it produced one. |
| Error         | string | Why this step failed, when it did.                               |

#### List Jobs

Look through recent conversion jobs, optionally only the finished or failed ones.

**Required permissions:** `task.read`.

**Inputs**

| Field           | Type            | Required | Description                                                                                       |
| --------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------- |
| Status          | select (string) | No       | Only show jobs in this state. Leave blank for all. Available values: Processing, Finished, Error. |
| Tag             | string          | No       | Only show jobs you labelled with this tag.                                                        |
| Maximum Results | integer         | No       | Roughly how many jobs to return. Also sets the page size. Minimum: 1. Default: 25.                |
| Page            | integer         | No       | Which page of results to start from. Leave blank to start at the beginning. Minimum: 1.           |

**Outputs**

| Field     | Type          | Description                                                           |
| --------- | ------------- | --------------------------------------------------------------------- |
| Jobs      | object\_array | The jobs that matched, each with its id, status, tag, and timestamps. |
| Next Page | integer       | Page number to request next, when more jobs are available.            |

#### List Supported Conversions

Check which formats CloudConvert can convert between, and what each conversion costs in credits.

**Required permissions:** `task.read`.

**Inputs**

| Field           | Type    | Required | Description                                                         |
| --------------- | ------- | -------- | ------------------------------------------------------------------- |
| From Format     | string  | No       | Only show conversions starting from this format.                    |
| To Format       | string  | No       | Only show conversions producing this format.                        |
| Operation       | string  | No       | Only show one kind of operation, such as converting or compressing. |
| Maximum Results | integer | No       | How many conversions to return at most. Minimum: 1. Default: 100.   |

**Outputs**

| Field       | Type          | Description                                                                |
| ----------- | ------------- | -------------------------------------------------------------------------- |
| Conversions | object\_array | The supported conversions, each with its formats, engine, and credit cost. |

#### Get Account Usage

See how many conversion credits are left on the connected CloudConvert account.

**Required permissions:** `user.read`.

**Inputs**

No input fields are required in this catalog entry.

**Outputs**

| Field             | Type    | Description                                       |
| ----------------- | ------- | ------------------------------------------------- |
| Credits Remaining | integer | Conversion credits left on the account.           |
| Email             | string  | Email address of the connected account.           |
| Username          | string  | Username of the connected account, if it has one. |
| Account ID        | string  | Identifier of the connected account.              |

### Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

#### Job Finished

Starts the workflow when a CloudConvert job completes successfully, with the download link ready.

StackAI registers and secures this webhook with CloudConvert automatically when you enable the trigger. If CloudConvert gets a non-2xx response from this URL it retries a few times, and on an HTTP 410 response it auto-disables the subscription; re-enable it from the Webhooks page at <https://cloudconvert.com/dashboard/api/v2/webhooks> if that happens.

**Required permissions:** `webhook.write`, `webhook.read`, `task.read`.

**Configuration**

| Field            | Type   | Required | Description                                                                                              |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| Only Jobs Tagged | string | No       | Only start the workflow for jobs you labelled with this tag. Leave blank to react to every finished job. |

**Event inputs**

| Field         | Type     | Required | Description                                                              |
| ------------- | -------- | -------- | ------------------------------------------------------------------------ |
| Job ID        | string   | Yes      | Identifier of the job that finished.                                     |
| Tag           | string   | No       | The label set on the job when it was created.                            |
| Download Link | string   | No       | Temporary link to the finished file. Expires 24 hours after the job ran. |
| File Name     | string   | No       | Name of the finished file.                                               |
| Finished At   | datetime | No       | When the job finished.                                                   |

**Outputs**

| Field         | Type     | Description                                                              |
| ------------- | -------- | ------------------------------------------------------------------------ |
| Job ID        | string   | Identifier of the job that finished.                                     |
| Tag           | string   | The label set on the job when it was created.                            |
| Download Link | string   | Temporary link to the finished file. Expires 24 hours after the job ran. |
| File Name     | string   | Name of the finished file.                                               |
| Finished At   | datetime | When the job finished.                                                   |

#### Job Failed

Starts the workflow when a CloudConvert job fails, so you can alert someone or retry.

StackAI registers and secures this webhook with CloudConvert automatically when you enable the trigger. If CloudConvert gets a non-2xx response from this URL it retries a few times, and on an HTTP 410 response it auto-disables the subscription; re-enable it from the Webhooks page at <https://cloudconvert.com/dashboard/api/v2/webhooks> if that happens.

**Required permissions:** `webhook.write`, `webhook.read`, `task.read`.

**Configuration**

| Field            | Type   | Required | Description                                                                                            |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| Only Jobs Tagged | string | No       | Only start the workflow for jobs you labelled with this tag. Leave blank to react to every failed job. |

**Event inputs**

| Field       | Type     | Required | Description                                                                  |
| ----------- | -------- | -------- | ---------------------------------------------------------------------------- |
| Job ID      | string   | Yes      | Identifier of the job that failed.                                           |
| Tag         | string   | No       | The label set on the job when it was created.                                |
| Error       | string   | No       | Why the job failed, in plain language.                                       |
| Failed Step | string   | No       | Which step of the job failed, such as downloading the file or converting it. |
| Failed At   | datetime | No       | When the job failed.                                                         |

**Outputs**

| Field       | Type     | Description                                                                  |
| ----------- | -------- | ---------------------------------------------------------------------------- |
| Job ID      | string   | Identifier of the job that failed.                                           |
| Tag         | string   | The label set on the job when it was created.                                |
| Error       | string   | Why the job failed, in plain language.                                       |
| Failed Step | string   | Which step of the job failed, such as downloading the file or converting it. |
| Failed At   | datetime | When the job failed.                                                         |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/cloudconvert.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
