Why CloudConvert URL to PDF Conversion Fails with a Timeout

If CloudConvert URL-to-PDF conversion times out, first identify what the URL points to. A webpage that needs to be rendered should use the capture-website operation with output_format: "pdf". A URL that directly serves a file should use import/url, followed by convert if the file needs conversion. These are different workflows, and the word “timeout” alone does not identify which part failed.

CloudConvert documents a default task timeout of five hours for website capture. That setting is separate from the timeout in your SDK, HTTP client, reverse proxy, or application while it waits for a response. Inspect the job and task status, save the full error, and determine which layer timed out before changing settings. CloudConvert’s Capture Website documentation describes the task timeout and capture operation.

1. Choose the right operation for the URL

What the URL serves	CloudConvert workflow	What happens
A webpage, such as an article or dashboard	`capture-website`	A browser renders the page and produces a PDF.
A downloadable file, such as a PDF or DOCX	`import/url`, then optionally `convert`	CloudConvert downloads the file; conversion operates on that file.

A URL that looks like a page but redirects to a file can make this distinction less obvious. Open it in a browser and inspect the final destination and response behavior. If the desired output is a print-style rendering of the page, use capture. If the URL already returns the document you want to process, import it as a file.

2. Diagnose the timeout before changing settings

Save the evidence. Record the job ID, task ID, operation, status, exact error message and code, timestamps, URL, and relevant request settings. Do not diagnose from a client-side timeout message alone.
Inspect the job and its tasks. CloudConvert jobs expose statuses such as waiting, processing, finished, and error; inspect the individual task to find its operation and error details. See the Jobs API reference and Tasks API reference.
Check which clock expired. Compare the elapsed time and error from CloudConvert’s task with your HTTP client, SDK, web server, proxy, or job runner logs. A caller can stop waiting while CloudConvert’s asynchronous job is still processing.
Verify the URL from the service’s perspective. Check redirects, authentication requirements, and whether the resource is actually a webpage or a downloadable file. A URL that works in your logged-in browser may require authorization headers.
Check page readiness. If the page adds content after its initial load, consider waiting for a CSS selector that appears when the needed content is ready. This is a documented capture option, not a universal timeout fix.
Only then adjust the relevant timeout or integration behavior. Raising the task timeout cannot by itself make an inaccessible page accessible or fix a caller that gives up too soon.

3. Capture a webpage as a PDF

Create a job with a capture-website task and an export/url task. The following cURL request uses CloudConvert’s asynchronous Jobs API. Replace the placeholder with your API key and the example page URL with your target.

cURL

curl -X POST "https://api.cloudconvert.com/v2/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": {
      "capture-page": {
        "operation": "capture-website",
        "url": "https://example.com",
        "output_format": "pdf"
      },
      "export-pdf": {
        "operation": "export/url",
        "input": "capture-page"
      }
    }
  }'

Python

import os
import requests

api_key = os.environ["CLOUDCONVERT_API_KEY"]

response = requests.post(
    "https://api.cloudconvert.com/v2/jobs",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "tasks": {
            "capture-page": {
                "operation": "capture-website",
                "url": "https://example.com",
                "output_format": "pdf",
            },
            "export-pdf": {
                "operation": "export/url",
                "input": "capture-page",
            },
        }
    },
    timeout=30,
)
response.raise_for_status()
job = response.json()["data"]
print("Job ID:", job["id"])
print("Status:", job["status"])
print("Inspect this job using the CloudConvert Jobs API.")

The 30-second value here limits how long this client waits for the job-creation HTTP response. It does not set the capture task’s duration. The create-job endpoint is asynchronous and returns before the work necessarily finishes.

Node.js

const apiKey = process.env.CLOUDCONVERT_API_KEY;
if (!apiKey) throw new Error('Set CLOUDCONVERT_API_KEY');

const response = await fetch('https://api.cloudconvert.com/v2/jobs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tasks: {
      'capture-page': {
        operation: 'capture-website',
        url: 'https://example.com',
        output_format: 'pdf',
      },
      'export-pdf': {
        operation: 'export/url',
        input: 'capture-page',
      },
    },
  }),
});

if (!response.ok) {
  throw new Error(`CloudConvert job creation failed: ${response.status} ${await response.text()}`);
}
const { data: job } = await response.json();
console.log('Job ID:', job.id);
console.log('Status:', job.status);

Set the capture task timeout

The capture-website task accepts timeout in seconds; CloudConvert documents a five-hour default. For example, add "timeout": 3600 to the capture-page task to configure a one-hour task timeout. Choose a limit appropriate to your workload. This controls when CloudConvert cancels that task; it does not extend a caller’s HTTP request timeout. A longer limit also does not resolve a page that cannot be reached or never presents the needed content. Refer to the operation’s parameter documentation for its supported options.

4. Import a URL that points directly to a file

For a directly downloadable input file, use import/url. Add convert only if the imported file needs conversion. This example converts a DOCX file to PDF, then creates a temporary download URL.

curl -X POST "https://api.cloudconvert.com/v2/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": {
      "import-file": {
        "operation": "import/url",
        "url": "https://example.com/document.docx"
      },
      "convert-file": {
        "operation": "convert",
        "input": "import-file",
        "output_format": "pdf"
      },
      "export-pdf": {
        "operation": "export/url",
        "input": "convert-file"
      }
    }
  }'

If the URL already serves the PDF you want, import the file and omit the conversion task if no transformation is needed. CloudConvert’s Import Files documentation describes import/url and its URL, filename, and headers parameters. The Quickstart Guide shows the import, convert, and export job pattern.

5. Authentication and content that loads late

Protected pages and files

If a file download requires authorization, import/url supports a headers object for additional request headers. CloudConvert’s HTML-to-PDF documentation also describes custom authorization headers for protected URL resources. Supply only the credentials needed to fetch the intended resource, and avoid exposing secrets in logs or client-side code. The exact headers depend on the site’s authentication scheme.

Delayed page content

For capture, the HTML-to-PDF documentation says the browser can wait for a custom CSS selector before generating the PDF. Use a selector that indicates the content you need is present, such as the main report container. This can help when useful content appears after initial page load. It cannot make a selector appear if the page fails to load that content, and the dossier does not establish it as a general remedy for every timeout. See CloudConvert’s HTML-to-PDF page.

6. Task timeout, caller timeout, and download expiry

What expired or failed	What it means	What to inspect
Capture task timeout	The configured CloudConvert task duration elapsed and the task was cancelled.	Task status, task error, configured `timeout`, and whether capture was the correct operation.
Caller or proxy timeout	Your application stopped waiting for an HTTP response; this alone does not prove the CloudConvert task failed.	Client, SDK, reverse proxy, web server, and worker logs; then query the job asynchronously.
Temporary export URL expired	The output link is no longer available for download; this is distinct from capture timing out.	Whether the task finished and when the export link was created. CloudConvert says tasks and their temporary URLs are available for 24 hours.

CloudConvert’s synchronous wait endpoint can be unsuitable for long-running work because network stacks may time out when no data is transferred for a while. Its Jobs API documentation recommends avoiding a blocked application wait for long jobs and describes asynchronous jobs with webhooks as beneficial. Prefer creating the job, storing its ID, and checking status or handling completion asynchronously. See the Jobs API reference and Export Files documentation.

7. Common errors and fixes

Symptom	Likely distinction to check	Next step
The API call times out, but no CloudConvert task error is recorded.	The caller, network stack, or proxy may have stopped waiting for the HTTP response.	Check caller logs and query the job by ID; use the asynchronous job flow rather than treating a long wait as proof of task failure.
The task reports a timeout.	The task’s configured duration elapsed. For website capture, the documented default is five hours.	Verify the operation and URL, inspect the task details, and adjust the task timeout only if the page is reachable and needs more time.
A webpage is treated like a file, or a file URL is treated like a page.	The wrong operation was selected.	Use `capture-website` for browser-rendered page output. Use `import/url` for a downloadable file.
The page or download works in your browser but not in the job.	The target may require authorization that is not present in the job request.	Check access requirements and configure supported custom headers for URL imports or protected HTML-to-PDF resources.
The PDF is missing content that appears after load.	The page may populate the relevant content after its initial render.	For website capture, use the documented CSS-selector wait option when a reliable readiness selector exists.
The job finished, but the result link cannot be downloaded.	The temporary export URL may have expired after its 24-hour availability window.	Retrieve the output sooner or create a new job if the original temporary link has expired.

These symptoms narrow down what to inspect; without the job’s status, task error, settings, and URL behavior, they do not establish the cause of a particular failure.

8. Performance, reliability, and cost considerations

Keep long work asynchronous. Create the job, save its ID, and check for completion or use a webhook. This avoids tying a user-facing request to the entire rendering duration. CloudConvert documents asynchronous job creation and webhook notification by default on its HTML-to-PDF page.
Set timeouts by layer. A short creation-request timeout can be reasonable because job creation returns asynchronously. Separately choose the capture task timeout and the application’s own job-wait policy.
Make retries evidence-based. Before retrying, determine whether the job is still processing, failed, or completed. Retrying without checking can create duplicate work. If a failure repeats, preserve the task details and the exact URL behavior for diagnosis.
Retrieve exports promptly. Temporary export URLs are available for 24 hours according to CloudConvert’s documentation. Download the result or send it to supported storage as part of the workflow.
Check current pricing for your workload. The supplied documentation establishes the job workflow and timeout behavior, not the cost of a specific capture or conversion. Review CloudConvert’s current pricing and account usage before estimating production cost.

9. Or skip the browser setup

If your goal is a clean screenshot of a webpage rather than a PDF, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF, and its parameters include PDF output. The API call is:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for options and request details. It accepts cookie or consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and whether the shot was billed. Its MCP server offers take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.

10. FAQ

Does CloudConvert’s five-hour default mean my HTTP request can wait five hours?

No. The documented default applies to the capture task. Your client or infrastructure has its own request and wait timeouts.

Not by itself. Check the page’s access requirements and whether the appropriate authorization headers can be supplied.

Is a temporary export URL timing out the same as a capture task timeout?

No. An expired result link is a download-availability issue after processing; CloudConvert documents temporary export URLs as available for 24 hours.

Should I use `capture-website` for a URL ending in `.pdf`?

Use the actual response and intended operation to decide. If the URL downloads the PDF file, use the file-import workflow; use capture when you want a browser-rendered page.