GetBulkDownloadStatus Service Operation

 

Gets the status of a bulk download request.

System_CAPS_ICON_note.jpg Note

You must use the same user credentials for the download request operation (either DownloadCampaignsByAccountIds or DownloadCampaignsByCampaignIds) and the GetBulkDownloadStatus polling operation.

Request | Response

Error Codes

Service: BulkService.svc v10 | Namespace: https://bingads.microsoft.com/CampaignManagement/v10

Request Element

The GetBulkDownloadStatusRequest object defines the elements of the request’s body. The elements must be in the same order as shown in the SOAP Request SOAP.

ElementDescriptionData Type
RequestIdThe identifier of the download request.

The DownloadCampaignsByAccountIds and DownloadCampaignsByCampaignIds operations return this element as the DownloadRequestId.
string

Request Headers

Set the required header elements for each service request. New customers are required to sign up for Bing Ads with a Microsoft Account, and to manage those accounts you must use OAuth. Existing users with legacy Bing Ads credentials may continue to specify the UserName and Password header elements. In future versions of the API, Bing Ads will transition exclusively to Microsoft Account authentication. For more information, see Getting Started With the Bing Ads API.

OAuth Authentication

These request headers are required for Managing User Authentication with OAuth.

ElementDescriptionData Type
AuthenticationTokenThe OAuth access token that represents a Microsoft Account user who has permissions to Bing Ads accounts.string
CustomerAccountIdThe identifier of the account that owns the entities in the request. This header element must have the same value as the AccountId body element when both are required.

Note: Required for most service operations, and as a best practice you should always specify this element.
string
CustomerIdThe identifier of the customer that contains and owns the account. If you manage an account of another customer, you should use that customer ID instead of your own customer ID.

Note: This element is required.
string
DeveloperTokenThe developer token used to access the Bing Ads API.string

Password Authentication

These request headers are required for legacy username and password authentication.

ElementDescriptionData Type
CustomerAccountIdThe identifier of the account that owns the entities in the request. This header element must have the same value as the AccountId body element when both are required.

Note: Required for most service operations, and as a best practice you should always specify this element.
string
CustomerIdThe identifier of the customer that contains and owns the account. If you manage an account of another customer, you should use that customer ID instead of your own customer ID.

Note: This element is required.
string
DeveloperTokenThe developer token used to access the Bing Ads API.string
PasswordThe Bing Ads user's sign-in password.string
UserNameThe Bing Ads user's sign-in user name. You must not set this element to a Microsoft account or email address. To authenticate a Microsoft account, use the AuthenticationToken header instead of UserName and Password.string

Request SOAP

The following example shows the complete request envelope.

<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v10">
    <Action mustUnderstand="1">GetBulkDownloadStatus</Action>
    <ApplicationToken i:nil="false"></ApplicationToken>
    <AuthenticationToken i:nil="false"></AuthenticationToken>
    <CustomerAccountId i:nil="false"></CustomerAccountId>
    <CustomerId i:nil="false"></CustomerId>
    <DeveloperToken i:nil="false"></DeveloperToken>
    <Password i:nil="false"></Password>
    <UserName i:nil="false"></UserName>
  </s:Header>
  <s:Body>
    <GetBulkDownloadStatusRequest xmlns="https://bingads.microsoft.com/CampaignManagement/v10">
      <RequestId i:nil="false"></RequestId>
    </GetBulkDownloadStatusRequest>
  </s:Body>
</s:Envelope>

Response Body

ElementDescriptionData Type
ErrorsAn array of OperationError objects corresponding to errors encountered during the system processing of the bulk file after your download request was submitted.OperationError array
ForwardCompatibilityMapThe list of key and value strings for forward compatibility. This element can be used to avoid otherwise breaking changes when new elements are added in future releases.

Note: Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for the GetBulkDownloadStatusResponse message object.
KeyValuePairOfstringstring array
PercentCompleteThe progress completion percentage for system processing of the bulk download file.int
RequestStatusThe status of the download. The possible values are as follows.

Completed - The download completed successfully.

InProgress - The download is in progress.

Failed - The download failed. You may submit a new download with fewer entities, without performance data, or try again to submit the same download later.

FailedFullSyncRequired - The request's LastSyncTimeInUTC element must be set to null, for example if the specified account was included in a data migration. After requesting a full download, you may begin requesting delta downloads again.
string
ResultFileUrlThe URL that contains the download data. This element contains the URL when the Status element is Success.

Note: You have five minutes from the time that GetBulkDownloadStatus returns success to start downloading the file. If you do not start the download within this time period, you will need to call GetBulkDownloadStatus again to get a new URL.

The download file is compressed (in zip format), so you must unzip the file to access the data.

For information about the bulk file format, see Bulk File Schema.
string

Response Header

ElementDescriptionData Type
TrackingIdThe identifier of the log entry that contains the details of the API call.string

Response SOAP

The following example shows the complete response envelope.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v10">
    <TrackingId p4:nil="false" xmlns:p4="http://www.w3.org/2001/XMLSchema-instance"></TrackingId>
  </s:Header>
  <s:Body>
    <GetBulkDownloadStatusResponse xmlns="https://bingads.microsoft.com/CampaignManagement/v10">
      <Errors p4:nil="false" xmlns:p4="http://www.w3.org/2001/XMLSchema-instance">
        <OperationError>
          <Code></Code>
          <Details p4:nil="false"></Details>
          <ErrorCode p4:nil="false"></ErrorCode>
          <Message p4:nil="false"></Message>
        </OperationError>
      </Errors>
      <ForwardCompatibilityMap xmlns:e1="http://schemas.datacontract.org/2004/07/System.Collections.Generic" p5:nil="false" xmlns:p5="http://www.w3.org/2001/XMLSchema-instance">
        <e1:KeyValuePairOfstringstring>
          <e1:key p5:nil="false"></e1:key>
          <e1:value p5:nil="false"></e1:value>
        </e1:KeyValuePairOfstringstring>
      </ForwardCompatibilityMap>
      <PercentComplete></PercentComplete>
      <RequestStatus p4:nil="false" xmlns:p4="http://www.w3.org/2001/XMLSchema-instance"></RequestStatus>
      <ResultFileUrl p4:nil="false" xmlns:p4="http://www.w3.org/2001/XMLSchema-instance"></ResultFileUrl>
    </GetBulkDownloadStatusResponse>
  </s:Body>
</s:Envelope>

Poll for downloads at reasonable intervals. You know your data better than anyone. If you download an account that is well less than one million keywords, consider polling at 15 to 20 second intervals. If the account contains about one million keywords, consider polling at one minute intervals after waiting five minutes. For accounts with about four million keywords, consider polling at one minute intervals after waiting 10 minutes.

If the service operation fails, it throws a FaultException exception, which contains one or more of the Bing Ads API error data objects. For information about the fault detail objects, see Bulk Error Data Objects and Handling Service Errors and Exceptions.The following are example error codes that the error objects can include when using this service operation. For all documented error codes, please see Bing Ads Operation Error Codes.

Symbolic
InvalidCredentials
CampaignServiceInvalidDownloadRequestId

DownloadCampaignsByAccountIds
DownloadCampaignsByCampaignIds

Show: