↑ ↓ to move ↵ to open
eBay API reference

eBay Promotions Search

ebay.search.promotions

See the sponsored listings and ad placements on a search results page.

At a glance

Endpoint ID
ebay.search.promotions
Price
2–5 credits per call; failed calls are free
Runs for up to
180 seconds
Request
POST /execute
Run an endpoint
MCP tool when pinned
ebay__search__promotions
Pin tools
OpenAPI
openapi.json
Download

Request

Send the endpoint ID as capability and its fields as input. Set UPSCRAPE_API_KEY to your key first.

curl --request POST \  --url https://data.upscrape.com/execute \  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \  --header "Content-Type: application/json" \  --header "Prefer: wait=30" \  --data '{  "capability": "ebay.search.promotions",  "input": {    "limit": 60,    "page": 1,    "query": "used laptop"  }}'

Input

FieldTypeRequiredWhat it doesExample
query string yes Search query. used laptop
limit integer no Maximum number of results to return. Allowed values: 60, 120, 240. 60
page integer no One-based result page to fetch. From 1 to 100. 1

Response

A finished call answers with HTTP 200; the data is in results[0].data, and billing.credits_charged is what it cost. A call still running after the wait answers 202: see jobs and results.

This is results[0].data from a real run:

results[0].data
{  "banners": [    {      "location": "below_pagination",      "filled": true,      "height": "-1",      "placement_id": "278",      "type": "html",      "width": "-1"    }  ],  "sponsored_listings": [    {      "item_id": "327340271850",      "leaf_category": "177",      "promoted": true,      "rank": 0,      "variant_id": "0"    },    {      "item_id": "264987527030",      "leaf_category": "177",      "promoted": true,      "rank": 1,      "variant_id": "0"    }  ]}

Fields

FieldTypeWhat it isExample
sponsored_listings[].item_id string eBay's ID for the listing. 327340271850
sponsored_listings[].leaf_category string eBay's ID for the listing's most specific category. 177
sponsored_listings[].promoted boolean Whether the listing is a paid placement. true
sponsored_listings[].rank integer The listing's place in the results, starting at 0. 0
sponsored_listings[].variant_id string eBay's ID for the listing variant. 0
banners array The banner ads on the search page. 1 records
banners[].filled boolean true
banners[].height string -1
banners[].location string Where the banner sits on the search page. below_pagination
banners[].placement_id string eBay's ID for the promotion slot. 278
banners[].type string The banner's format. html
banners[].width string -1
sponsored_listings array Listings shown as sponsored. 3 records

If a call fails

A failed call costs nothing. The response carries an error.code you can branch on; Errors and retries lists every code and which ones to retry.

Other eBay endpoints

Something missing or unclear? Ask the team that builds the eBay endpoints.