Download Status
Inspects a task’s download state and HTTP attempt history to troubleshoot pending, failed, or completed downloads
Endpoint
GET /api/v3/tasks/{taskId}/download-status
Path Parameters
| Name | Type | Description |
|---|---|---|
| taskId | string | Required. Download task ID returned by job start, in download task records from crawl requests, or embedded in a 202 Location URL from async task endpoints |
Responses
200 (OK)
Returns DownloadTaskStatus as a DownloadTaskStatus.
400 (Bad Request)
Invalid request parameters. Refer to the response text for more information
403 (Forbidden)
Access restricted. Refer to the response text for more information
404 (Not Found)
Task not found
Data Contracts
DownloadTaskStatus
Current state and request history for a download task
Fields:
| Name | Type | Description |
|---|---|---|
| Url | string | URL associated with the download task |
| State | DownloadTaskState | Current download task state |
| Result | DownloadInfo or null | Optional. Final download attempt details, or null when no attempt result is available |
| IntermedResults | array of DownloadInfo or null | Optional. Earlier attempt details such as redirects or proxy retries. Null means no attempt history is available; an empty array means only the final result exists |
DownloadTaskState
Lifecycle states for a download task
Enumeration values:
| Name | Description |
|---|---|
| Handled | The downloader finished handling the task. When DownloadTaskStatus.Result is present, inspect IsSuccess and HttpStatusCode to determine request success |
| AccessDeniedForRobots | The target URL was blocked by robots.txt |
| AllRequestGatesExhausted | All request gateways, such as proxies or host IP addresses, were exhausted without a successful response |
| Created | The task was created but has not started |
| InProgress | The task is currently being downloaded |
| Deleted | The task was deleted |
DownloadInfo
HTTP request and response details for one download attempt
Fields:
| Name | Type | Description |
|---|---|---|
| Method | string | HTTP method |
| Url | string | Request URL |
| IsSuccess | bool | Whether the request completed successfully |
| HttpStatusCode | int | HTTP response status code |
| ReasonPhrase | string | HTTP reason phrase |
| RequestHeaders | array of HttpHeader | HTTP headers sent with the request |
| ResponseHeaders | array of HttpHeader | HTTP headers received in the response |
| RequestCookies | array of Cookie | Cookies sent with the request |
| ResponseCookies | array of Cookie | Cookies received in the response |
| RequestDateUtc | datetime | Date and time when the request was sent, in UTC |
| DownloadTimeSec | double | Download time in seconds |
| ViaProxy | bool | Whether the request was made through a proxy |
| WaitTimeSec | double | Total delay in seconds before the request was executed |
| CrawlDelaySec | int | Crawl-delay portion of the wait time, in seconds |
HttpHeader
Represents one HTTP header with its name and one or more values
Fields:
| Name | Type | Description |
|---|---|---|
| Name | string | HTTP header name, for example User-Agent or Authorization |
| Values | array of string | One or more values for this header |
Cookie
HTTP cookie sent with a request or received in a response
See HTTP cookies for protocol-level background.
Fields:
| Name | Type | Description |
|---|---|---|
| Name | string | Cookie name |
| Value | string or null | Optional. Cookie value, or null when absent |
| Domain | string or null | Optional. Cookie domain attribute, or null when absent |
| Path | string or null | Optional. Cookie path attribute, or null when absent |
| HttpOnly | bool | Whether the cookie has the HttpOnly attribute |
| Secure | bool | Whether the cookie has the Secure attribute |
| Expires | datetime or null | Optional. Cookie expiration date and time, or null for a session cookie or unknown expiration |