eBay API · Endpoint

eBay Promotions Search API

Q: What do I send?

Send query. The input fields below list every option with its type and limits.

Q: Can my AI agent call it?

Yes, over MCP: the agent finds ebay.search.promotions, checks its price and runs it with the same credits as the REST API.

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

1 credit per call
Failed calls are free
Updated 14 Oct 2026
ebay.search.promotions

Start free, 100 credits API reference

Response completed

{  "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"    }  ]}

3 rows

#	Leaf category	Promoted	Rank	Item id
1	177	true	0	327340271850
2	177	true	1	264987527030
3	177	true	2	147465369570

Try it live, free

Input

What you send

The input object of the request, with every field the endpoint accepts.

Field	Type	Required	What it does	Example
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

Fields it returns

What each record in the response holds, with the values from the sample above.

Field	Type	What it is	Example
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

REST API · MCP server

Call it from your code, or ask your agent

Set UPSCRAPE_API_KEY to your key and copy a working request.

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"  }}'

import jsonimport osimport requestspayload = json.loads(r'''{  "capability": "ebay.search.promotions",  "input": {    "limit": 60,    "page": 1,    "query": "used laptop"  }}''')response = requests.post(    "https://data.upscrape.com/execute",    headers={        "Authorization": f"Bearer {os.environ['UPSCRAPE_API_KEY']}",        "Content-Type": "application/json",        "Prefer": "wait=30",    },    json=payload,)response.raise_for_status()print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data.upscrape.com/execute", {  method: "POST",  headers: {    "Authorization": `Bearer ${process.env.UPSCRAPE_API_KEY}`,    "Content-Type": "application/json",    "Prefer": "wait=30",  },  body: JSON.stringify({  "capability": "ebay.search.promotions",  "input": {    "limit": 60,    "page": 1,    "query": "used laptop"  }}),});if (!response.ok) {  throw new Error(`Upscrape request failed: ${response.status}`);}console.log(JSON.stringify(await response.json(), null, 2));