> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://uploadcare.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server. # Proxy > Utilize the power of Uploadcare CDN with one minimal change on your side. When you need to get all the benefits of a powerful CDN without *explicitly* uploading files to a new location, use Proxy. It automatically retrieves files from existing remote locations and delivers them using [Uploadcare CDN](/docs/delivery/). Utilizing a CDN can significantly improve your users' browsing experience, and open up more technical opportunities by providing on-the-fly [image transformation and optimization](/docs/transformations/image/#image-transformations-list). It's easy to integrate, requiring only one URL modification: ``` https://endpoint.ucr.io/ + https://yoursite.com/assets/image.jpg = https://endpoint.ucr.io/https://yoursite.com/assets/image.jpg ``` When the first request is made, the source file is instantly uploaded to your Uploadcare storage. Once it is cached on our CDN, all subsequent requests will fetch the file from the closest CDN node. This is the simplest way to [implement responsive images](/docs/responsive-images/), \*\*lower traffic costs, or just try us out without investing too much time into migration. ## Usage ### Step 1. Setup your Proxy \[#usage-domains] Go to [Uploadcare Dashboard](https://app.uploadcare.com/projects/-/delivery/configure/): 1. Specify the allowed domain names that host your files. The Proxy will recognize these domains and block delivery from others. 2. Optionally, you can edit your Proxy Endpoint to use custom domain name to serve files. See [down below](#usage-endpoint). ### Step 2. Add Proxy prefix \[#usage-prefixes] Combine the Proxy prefix with the file URL, including any query string, provided the file URL is from an allowed domain. The Proxy prefix should include your Endpoint. ``` https://endpoint.ucr.io/ + https://yoursite.com/assets/image.jpg = https://endpoint.ucr.io/https://yoursite.com/assets/image.jpg ``` The original file will remain at its original place, so that older references will work as well. ### Step 3. Apply image operations \[#usage-processing] You can apply [image processing operations](/docs/transformations/image/#image-transformations-list) by adding one of the respective URL directives **between** the prefix and the media URL. ``` https://endpoint.ucr.io/-/preview/-/resize/500x/https://yoursite.com/assets/image.jpg ``` As a result, `image.jpg` will be processed and delivered with Uploadcare CDN. Note: Uploadcare processes images on the fly. We count storage space only for original files. Processed versions don't occupy any space in your storage limit. ### Endpoint customization (optional) \[#usage-endpoint] Uploadcare provides different domain options for serving and fetching files.\ They fall into two categories: **CDN domains** (for delivery) and **Proxy domains** (for fetching from remote sources). #### CDN domains (for delivery) * **Auto-generated:**\ `.ucarecd.net` * Created automatically for every project. * Free and ready to use instantly. * Recommended for most users. * **Custom CNAME:**\ `cdn.domain.com` * Requires creating a DNS CNAME record pointing to `.ucarecd.net`. * \$25/month. * Use when you need file delivery under your own branded domain or integration with existing CDN infrastructure. #### Proxy domains (for fetching) * **Auto-generated:**\ `.ucr.io` * Created automatically for every project. * Used when you need to fetch files from remote sources via Proxy. * Free, works out of the box. * **Custom Proxy domain:**\ `yourdomain.ucr.io` * Free, can be registered through Uploadcare support. * Use if you want proxy requests to appear under your own branded domain inside the `ucr.io` zone. * Same infrastructure and performance as the default domain. * **Custom CNAME:**\ `proxy.yourdomain.com` * Paid feature, also requires registration and setup via Uploadcare support. * See [Pricing](https://uploadcare.com/pricing/) for plan details. * Use if you need delivery fully under your own domain (CNAME to `ucr.io`). #### Which one do I need? | Use case | Recommended option | | ------------------------------------------- | ----------------------- | | Deliver files from Uploadcare CDN | `.ucarecd.net` | | Deliver files under your own branded domain | `cdn.domain.com` | | Fetch files from remote sources via Proxy | `.ucr.io` | | Fetch files under your own Proxy domain | `yourdomain.ucr.io` | --- When fetching the source file from a remote server, the Proxy will first attempt a `HEAD` request (or `OPTIONS`, depending on the remote server) before the actual `GET` to check the source file’s availability. The remote server must handle `HEAD` requests correctly. ## Possible errors \[#errors] List of errors you might get when using Proxy: | **Error** | **Description** | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \[HTTP 400] `Domain is not registered` | You did not register a Proxy domain for your sites by dropping us a line at [help@uploadcare.com](mailto:help@uploadcare.com). | | \[HTTP 400] `Domain is not allowed` | You tried fetching a file from a domain that was not allowed. Check settings or contact us to add the domain as allowed for your account. | | \[HTTP 400] `Failed to parse file URL` | Your prefix was added to an invalid URL. Consider checking that URL. | | \[HTTP 404] | You tried fetching an unreachable file. Consider checking its URL. | | \[HTTP 502] `'is_ready' timeout` | A problem occurred when trying to upload a file to our storage. Try again later and if it didn't help you always can [contact us](mailto:help@uploadcare.com). | | Other errors | Proxy uses the `from_url` method, so you can also get general [errors](https://uploadcare.com/docs/api/upload/errors) related to the Upload API or specific to the `from_url` [method](https://uploadcare.com/docs/api/upload/upload/from-url-upload) | ## Proxy billing \[#billing] This feature is free and available across all plans. It is important to note that proxy uses your project upload units and storage limits since files are fetched and saved first before they are available on Uploadcare's CDN.