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.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com
URI parameters
| Parameter | Type | Description |
|---|---|---|
| report_task_statuses | string | This query 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. See TaskStatusEnum for supported values. Occurrence: Optional |
| limit | string | Specifies the maximum number of report tasks to return on a page in the paginated response. Default: 10 Maximum: 500 Occurrence: Optional |
| offset | string | Specifies 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 Occurrence: Optional |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.
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/field | Type | Description |
|---|---|---|
| href | string | The URI of the current page of results from the result set. Occurrence: Conditional |
| limit | integer | The 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 |
| next | string | The 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. Occurrence: Conditional |
| offset | integer | The 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. Occurrence: Conditional |
| prev | string | The 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. Occurrence: Conditional |
| total | integer | The total number of items retrieved in the result set. Occurrence: Conditional |
| reportTasks | array of ReportTask | A list of report tasks contained on this page from the paginated response. Occurrence: Always |
| reportTasks.campaignIds | array 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. Occurrence: Conditional |
| reportTasks.channels | array of ChannelEnum | The channel for the advertising campaign that will be included in the report task. This value indicates whether the data included in the report task is for an Onsite or Offsite advertising campaign. Occurrence: Conditional |
| reportTasks.dateFrom | string | The date defining the start of the timespan covered by the report, formatted as an ISO 8601 timestamp. Occurrence: Always |
| reportTasks.dateTo | string | The date defining the end of the timespan covered by the report, formatted as an ISO 8601 timestamp. Occurrence: Always |
| reportTasks.dimensions | array of Dimension | A list containing the dimension in the report. Occurrence: Always |
| reportTasks.dimensions.annotationKeys | array of string | A list of annotations associated with the dimension of the report. Occurrence: Always |
| reportTasks.dimensions.dimensionKey | string | The name of the dimension on which the report is based. A dimension is an attribute to which the report data applies. Occurrence: Always |
| reportTasks.fundingModels | array of FundingModelEnum | The funding model for the campaign that shall be included in the report.
Occurrence: Conditional |
| reportTasks.inventoryReferences | array 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 |
| reportTasks.inventoryReferences.inventoryReferenceId | string | The unique identifier of a single-item listing or a multi-variation listing. Occurrence: Conditional |
| reportTasks.inventoryReferences.inventoryReferenceType | InventoryReferenceTypeEnum | Indicates the type of item indicated by the inventoryReferenceId. Occurrence: Conditional |
| reportTasks.listingIds | array 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 |
| reportTasks.marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace used by the report task. Occurrence: Always |
| reportTasks.metricKeys | array of string | A list of metrics for the report task. Occurrence: Always |
| reportTasks.reportExpirationDate | string | 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. Occurrence: Always |
| reportTasks.reportFormat | ReportFormatEnum | Indicates the format of the report. Currently, only Occurrence: Always |
| reportTasks.reportHref | string | The URL of the generated report, which can be used to download the report once it has been generated. Occurrence: Always |
| reportTasks.reportId | string | A unique eBay-assigned ID for the report. Occurrence: Always |
| reportTasks.reportName | string | An eBay-assigned name for the report that's created by the createReportTask call. This name is unique for the seller. Occurrence: Always |
| reportTasks.reportTaskCompletionDate | string | The date the report task completed the report generation. Occurrence: Always |
| reportTasks.reportTaskCreationDate | string | The date the report task was created. Occurrence: Always |
| reportTasks.reportTaskExpectedCompletionDate | string | The date the report task is expected to complete the report generation. Occurrence: Always |
| reportTasks.reportTaskId | string | 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 |
| reportTasks.reportTaskStatus | TaskStatusEnum | Indicates the current state of the report task. Occurrence: Always |
| reportTasks.reportTaskStatusMessage | string | A status message with additional information about the report task. Occurrence: Conditional |
| reportTasks.reportType | ReportTypeEnum | 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.
| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 500 | Internal Server error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 35001 | API_MARKETING | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance. |
| 35029 | API_MARKETING | REQUEST | The 'limit' has to be greater than zero and less than {maxLimitValue}. |
| 35030 | API_MARKETING | REQUEST | The 'offset' cannot be less than zero {offset}. |
| 35109 | API_MARKETING | REQUEST | The 'report_task_statuses' {invalid_report_task_statuses} is invalid. Valid values are: {supportedReportTaskStatuses}. |
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 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.
GEThttps://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).