Prefetches content from origin servers to Dynamic Route for CDN (DCDN) points of presence (POPs). This eliminates back-to-origin requests when users request the resource for the first time.


  • You can call the RefreshDcdnObjectCaches operation to refresh content and call the PreloadDcdnObjectCaches operation to prefetch content.
  • DCDN supports POST requests in which parameters are sent as a form.
  • By default, each Alibaba Cloud account can submit up to 1,000 URLs per day. If the daily peak bandwidth value of your workloads exceeds 200 Mbit/s, you can submit a ticket to apply for an increased upper limit. Alibaba Cloud will review your application and then increase the quota accordingly.
  • Each Alibaba Cloud account can submit up to 100 URLs in a request.
  • The prefetch queue of each Alibaba Cloud account can contain up to 50,000 URLs. DCDN executes prefetch tasks based on the time at which you submit the URLs.
  • You can call this operation up to 15 times per second per account.

Usage notes

  • After a refresh task is submitted and completed, the POPs immediately start to retrieve resources from the origin server. Therefore, a large number of refresh tasks cause a large number of concurrent download tasks. This increases the number of requests that are redirected to the origin server. The back-to-origin routing process consumes more bandwidth resources and the origin server may be overwhelmed.
  • The time required for a prefetch task to complete is proportional to the size of the prefetched file. In actual practice, most prefetch tasks take 5 to 30 minutes to complete. A task with a smaller average file size takes less time.
  • To allow Resource Access Management (RAM) users to perform this operation, you must first grant them the required permissions. For more information, see Authorize a RAM user to prefetch and refresh resources.


OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes PreloadDcdnObjectCaches

The operation that you want to perform. Set the value to PreloadDcdnObjectCaches.

ObjectPath String Yes

The path of the objects that you want to prefetch. Separate multiple URLs with line feed characters (\n) or a pair of carriage return and line feed characters (\r\n).

Area String No domestic

The acceleration region in which you want to prefetch objects. If you do not specify a region, the value overseas is used by default.

  • domestic: Chinese mainland
  • overseas: outside the Chinese mainland
L2Preload Boolean No true

Specifies whether to prefetch content to DCDN POPs. Default value: ecs. Valid values:

  • true: prefetches content to nodes that include L2 DCDN nodes.
  • false: prefetches content to L2 DCDN nodes or L3 DCDN nodes.

Response parameters

Parameter Type Example Description
PreloadTaskId String 95248880

The ID of the prefetch task. If multiple task IDs are returned, the IDs are separated by commas (,).

RequestId String E5BD4B50-7A02-493A-AE0B-97B9024B4135

The ID of the request.


Sample requests

&Common request parameters

Sample success responses

XML format

HTTP/1.1 200 OK


JSON format

HTTP/1.1 200 OK

  "PushTaskId" : "95248880",
  "RequestId" : "E5BD4B50-7A02-493A-AE0B-97B9024B4135"

Error codes

HttpCode Error code Error message Description
400 SingleRequest.OverLimit A maximum of 1000 URLs are supported for each request. The error message returned because the maximum number of URLs in one request has been reached. You can specify a maximum of 1,000 URLs in each request.
400 QuotaExceeded.Preload Your refresh attempts have exceeded the daily limit. The error message returned because the maximum number of refresh and prefetch requests on the current day has been reached.
400 InvalidObjectPath.Malformed The specified ObjectPath is invalid. The error message returned because the value specified for the ObjectPath parameter is invalid. Specify a valid value.
400 InvalidExtensiveDomain.ValueNotSupported The specified ExtensiveDomain is not supported. The error message returned because wildcard domain names are not supported.
400 PreloadQueueFull The warming queue is full; please try again later. The error message returned because the maximum number of URLs of the objects that are being prefetched has been reached. Try again later.

For a list of error codes, visit the API Error Center.