marketing APIv1.10.0

getReportTasks

GET
/ad_report_task
This method returns information on all the existing report tasks related to a seller.

Use the report_task_statuses query parameter to control which reports to return. You can paginate the result set by specifying a limit, which dictates how many report tasks to return on each page of the response. Use the offset parameter to specify how many reports to skip in the result set before returning the first result.

Input

Resource URI (production)

GET https://api.ebay.com/sell/marketing/v1/ad_report_task?

URI parameters

ParameterTypeDescription
report_task_statusesstringThis parameter filters the returned report tasks by their status. Supply a comma-separated list of the report statuses you want returned. The results are filtered to include only the report statuses you specify.

Note: The results might not include some report tasks if other search conditions exclude them.

Valid values:
   PENDING
   SUCCESS
   FAILED

Occurrence: Optional

limitstringSpecifies the maximum number of report tasks to return on a page in the paginated response.

Default: 10
Maximum: 500

Occurrence: Optional

offsetstringSpecifies the number of report tasks to skip in the result set before returning the first report in the paginated response.

Combine offset with the limit query parameter to control the reports returned in the response. For example, if you supply an offset of 0 and a limit of 10, the response contains the first 10 reports from the complete list of report tasks retrieved by the call. If offset is 10 and limit is 10, the first page of the response contains reports 11-20 from the complete result set.

Default: 0

Occurrence: Optional

HTTP request headers

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

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.

Output

HTTP response headers

Output container/fieldTypeDescription
hrefstringThe URI of the current page of results from the result set.

Occurrence: Conditional

limitintegerThe number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.

Occurrence: Conditional

nextstringThe URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.

Max length: 2048

Occurrence: Conditional

offsetintegerThe number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

Occurrence: Conditional

prevstringThe URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.

Max length: 2048

Occurrence: Conditional

totalintegerThe total number of items retrieved in the result set.

If no items are found, this field is returned with a value of 0.

Occurrence: Conditional

reportTasksarray of ReportTaskA list of report tasks contained on this page from the paginated response.

Occurrence: Always

reportTasks.campaignIdsarray of stringA list of campaign IDs to be 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.

Note: Currently, you can specify only one campaign ID.

Occurrence: Conditional

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

Occurrence: Always

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

Occurrence: Always

reportTasks.dimensionsarray of DimensionA list containing the dimension in the report.

Occurrence: Always

reportTasks.dimensions.annotationKeysarray of stringA list of annotations associated with the dimension of the report.

Occurrence: Always

reportTasks.dimensions.dimensionKeystringThe name of the dimension on which the report is based.

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

Occurrence: Always

reportTasks.inventoryReferencesarray of InventoryReferenceIf 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 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

reportTasks.inventoryReferences.inventoryReferenceIdstringThe 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

reportTasks.inventoryReferences.inventoryReferenceTypeInventoryReferenceTypeEnumIndicates 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

reportTasks.listingIdsarray of stringIf 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

reportTasks.marketplaceIdMarketplaceIdEnumThe ID of the eBay marketplace used by the report task.

Occurrence: Always

reportTasks.metricKeysarray of stringA list of metrics for the report task.

Occurrence: Always

reportTasks.reportExpirationDatestringThe 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

reportTasks.reportFormatReportFormatEnumIndicates the format of the report. Currently, only TSV_GZIP is supported.

Occurrence: Always

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

Occurrence: Always

reportTasks.reportIdstringA unique eBay-assigned ID for the report.

Occurrence: Always

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

Occurrence: Always

reportTasks.reportTaskCompletionDatestringThe date the report task completed the report generation.

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

Occurrence: Always

reportTasks.reportTaskCreationDatestringThe date the report task was created.

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

Occurrence: Always

reportTasks.reportTaskExpectedCompletionDatestringThe date the report task is expected to complete the report generation.

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

Occurrence: Always

reportTasks.reportTaskIdstringThe 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

reportTasks.reportTaskStatusTaskStatusEnumIndicates the current state of the report task.

Occurrence: Always

reportTasks.reportTaskStatusMessagestringA status message with additional information about the report task.

Occurrence: Conditional

reportTasks.reportTypeReportTypeEnumIndicates 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
400Bad Request
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.
35029API_MARKETINGREQUESTThe 'limit' has to be greater than zero and less than {maxLimitValue}.
35030API_MARKETINGREQUESTThe 'offset' cannot be less than zero {offset}.
35109API_MARKETINGREQUESTThe 'report_task_statuses' {invalid_report_task_statuses} is invalid. Valid values are: {supportedReportTaskStatuses}.

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 Report Tasks

This sample returns all the report tasks with as status of PENDING or SUCCESS and limits the response set to 10 report tasks.

Input

The inputs are a list of report_task_statuses and the limit field.
GET
https://api.ebay.com/sell/marketing/v1/ad_report_task?report_task_statuses=PENDING,SUCCESS&limit=10

Output

If the call is successful, it returns all report tasks that are currently running (PENDING), or those that have generated their reports (SUCCESS).