Skip to main content

GET/ad_report_task/{report_task_id}

This call returns the details of a specific Promoted Listings report task, as specified by the report_task_id path parameter.

The report task includes the report criteria (such as the report dimensions, metrics, and included listing) and the report-generation rules (such as starting and ending dates for the specified report task).

Report-task IDs are generated by eBay when you call createReportTask. Get a complete list of a seller's report-task IDs by calling getReportTasks.

Input

Resource URI (production)

GET https://api.ebay.com/sell/marketing/v1/ad_report_task/{report_task_id}

URI parameters

ParameterTypeDescription
report_task_idstringA unique eBay-assigned ID for the report task that's generated when the report task is created by a call to createReportTask.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

This method has no additional required headers. See HTTP request headers- opens rest request components page for details.

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.marketing

See OAuth access tokens for more information.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

Response fields

Output container/fieldTypeDescription
campaignIdsarray of string

A list of IDs for the campaigns that are included in the report. A campaign ID is a unique eBay-assigned identifier of the campaign that's generated when the campaign is created.

Call getCampaigns to return the current campaign IDs for a seller.

Occurrence: Conditional

dateFromstring

The date defining the start of the timespan covered by the report, formatted as an ISO 8601 timestamp.

Occurrence: Always

dateTostring

The date defining the end of the timespan covered by the report, formatted as an ISO 8601 timestamp.

Occurrence: Always

dimensionsarray of Dimension

A list containing the dimension in the report.

Occurrence: Always

dimensions.annotationKeysarray of string

A list of annotations associated with the dimension of the report.

Occurrence: Always

dimensions.dimensionKeystring

The name of the dimension on which the report is based.

A dimension is an attribute to which the report data applies.

Occurrence: Always

inventoryReferencesarray of InventoryReference

If supplied in the request, this field returns a list of the seller's inventory reference IDs included in the report.

Each item is referenced by a pair of inventoryRefernceID and inventoryReferenceType values, where an inventory reference ID can be either a seller-defined SKU value or an inventoryItemGroupKey. An inventoryItemGroupKey is seller-defined ID for an inventory item group (a multiple-variation listing), and is created and used by the Inventory API.

Occurrence: Conditional

inventoryReferences.inventoryReferenceIdstring

The seller's inventory reference ID for an item that is managed with the Inventory API.

An inventory reference is either the ID of a single listing or the ID of the parent of an item group listing (a multi-variation listing, such as a shirt that is available in multiple sizes and colors).

Required if if you supply an inventoryReferenceType.

Occurrence: Conditional

inventoryReferences.inventoryReferenceTypeInventoryReferenceTypeEnum

Indicates the type of item indicated by the inventoryReferenceId.

This value can be set to either INVENTORY_ITEM or INVENTORY_ITEM_GROUP (if the ID points to a multi-variation listing).

Required if if you supply an inventoryReferenceId.

Occurrence: Conditional

listingIdsarray of string

If supplied in the request, this field returns a list of the listing IDs included in the report. A listing ID is an eBay-assigned ID that's generated when a listing is created.

Occurrence: Conditional

marketplaceIdMarketplaceIdEnum

The ID of the eBay marketplace used by the report task.

Occurrence: Always

metricKeysarray of string

A list of metrics for the report task.

Occurrence: Always

reportExpirationDatestring

The date after which the report is no longer be available. Reports are available for 30 days and you cannot download a report after it has expired.

Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ

Occurrence: Always

reportFormatReportFormatEnum

Indicates the format of the report. Currently, only TSV_GZIP is supported.

Occurrence: Always

reportHrefstring

The URL of the generated report, which can be used to download the report once it has been generated.

Occurrence: Always

reportIdstring

A unique eBay-assigned ID for the report.

Occurrence: Always

reportNamestring

An eBay-assigned name for the report that's created by the createReportTask call. This name is unique for the seller.

Occurrence: Always

reportTaskCompletionDatestring

The date the report task completed the report generation.

Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ

Occurrence: Always

reportTaskCreationDatestring

The date the report task was created.

Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ

Occurrence: Always

reportTaskExpectedCompletionDatestring

The date the report task is expected to complete the report generation.

Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ

Occurrence: Always

reportTaskIdstring

The unique eBay-assigned ID of the report task. This value is generated when the report task is created with a call to createReportTask.

Occurrence: Always

reportTaskStatusTaskStatusEnum

Indicates the current state of the report task.

Occurrence: Always

reportTaskStatusMessagestring

A status message with additional information about the report task.

Occurrence: Conditional

reportTypeReportTypeEnum

Indicates type of report associated with the report task.

Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200Success
404Not found
500Internal Server error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
35001API_MARKETINGAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.
35140API_MARKETINGREQUESTNo ReportTask found for 'report_task_id' {report_task_id}. Please correct the 'report_task_id' and try again.

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Get Specific Report Task

This sample retrieves the details of a specific report task.

Input

Specify the report task you want to retrieve using the report_task_id URI parameter. The ID for a report task is returned in the Location HTTP response header of the createReportTask call you used to create the task.

GEThttps://api.ebay.com/sell/marketing/v1/ad_report_task/1********4

Output

If successful, the call returns details of the specified report task.