### Quickstart: curl request to /v1/scrape

Source: https://sold-comps.com/docs

Sends a GET request to the /v1/scrape endpoint with a bearer token and keyword query. Returns sold listings for the specified keyword.

```bash
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/scrape?keyword=iphone+15+pro&count=10"
```

--------------------------------

### Authentication header example

Source: https://sold-comps.com/docs

Shows the required Authorization header format for all API requests except the RapidAPI channel. The token must start with 'sc_'.

```http
Authorization: Bearer sc_YOUR_KEY_HERE
```

--------------------------------

### Example sold response JSON

Source: https://sold-comps.com/docs

Example response for a sold listing scrape. Shows the item fields including soldPrice, soldCurrency, totalPrice, and seller metrics. The response is the default sold=true format.

```json
{
  "keyword": "iphone 15 pro",
  "page": 1,
  "totalItems": 40,
  "totalResults": "14,000+",
  "hasNextPage": true,
  "autoSelectedCategory": { "id": "9355", "name": "Cell Phones & Smartphones" },
  "items": [
    {
      "itemId": "256123456789",
      "url": "https://www.ebay.com/itm/256123456789?nordt=true",
      "thumbnailUrl": "https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l500.webp",
      "fullResThumbnailUrl": "https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l1600.webp",
      "epid": "20049285656",
      "title": "Apple iPhone 15 Pro 256GB Natural Titanium - Unlocked",
      "condition": "Pre-Owned",
      "conditionId": 3000,
      "sellerType": null,
      "buyingFormat": "buyItNow",
      "bestOfferAccepted": false,
      "bidCount": null,
      "categoryId": "9355",
      "listingType": "sold",
      "endedAt": "2026-03-10",
      "soldPrice": "899.99",
      "soldCurrency": "USD",
      "shippingPrice": "0.00",
      "shippingCurrency": "USD",
      "shippingType": "free",
      "totalPrice": "899.99",
      "sellerUsername": "top-deals-store",
      "sellerPositivePercent": 99.8,
      "sellerFeedbackScore": 14200,
      "itemLocation": "United States",
      "productRating": 4.5,
      "productReviewCount": 12,
      "scrapedAt": "2026-03-14T21:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Lookup eBay Item Detail via cURL

Source: https://sold-comps.com/docs

Example request to fetch item details using the cURL command-line tool.

```bash
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/item/168647489856"
```

--------------------------------

### GET /v1/scrape/max

Source: https://sold-comps.com/docs

Async Max Mode for server-side pagination of eBay sold listings. Requires bearer token authentication.

```APIDOC
## GET /v1/scrape/max

### Description
Async Max Mode for server-side pagination of eBay sold listings. Requires bearer token authentication.

### Method
GET

### Endpoint
https://api.sold-comps.com/v1/scrape/max

### Parameters
#### Query Parameters
- **keyword** (string) - Required - The search keyword for sold listings.
- **count** (integer) - Optional - Number of results to return (default 40, up to 200 with cookies).

### Request Example
```
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/scrape/max?keyword=iphone&count=100"
```

### Response
#### Success Response (200)
- **listings** (array) - List of sold listings with price, condition, date, seller.

#### Response Example
```json
{
  "listings": [
    {
      "price": 799.99,
      "condition": "Refurbished",
      "date": "2024-03-10",
      "seller": "seller789"
    }
  ]
}
```
```

--------------------------------

### Bulk Search Request

Source: https://sold-comps.com/docs

Example of a POST request to the bulk-search endpoint using curl. Requires an Authorization header with a valid API key.

```bash
curl -X POST "https://api.sold-comps.com/api/bulk-search" \
  -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["iphone 15 pro","macbook air m2","airpods pro"]}'
```

--------------------------------

### GET /v1/poshmark/sold

Source: https://sold-comps.com/docs

Returns one page of real Poshmark sold listing data for a given keyword. Each page returns up to 48 items.

```APIDOC
## GET /v1/poshmark/sold

### Description
Search Poshmark sold listings for a specific keyword. Each request costs 1 quota slot, or 2 slots if enrichment is enabled.

### Method
GET

### Endpoint
/v1/poshmark/sold

### Parameters
#### Query Parameters
- **keyword** (string) - Required - Poshmark search term.
- **page** (integer) - Optional - Page number (default: 1).
- **minPrice** (number) - Optional - Minimum price filter (USD).
- **maxPrice** (number) - Optional - Maximum price filter (USD).
- **department** (enum) - Optional - Poshmark department filter (all, women, men, kids, home, pets, electronics).
- **condition** (enum) - Optional - Condition filter (all, nwt).
- **brand** (string) - Optional - Filter by brand name.
- **sortBy** (enum) - Optional - Sort order (sold_recently, price_asc, price_desc, likes).
- **enrich** (boolean) - Optional - When true, adds detailed listing information (costs 2 quota slots).

### Response
#### Success Response (200)
- **listingId** (string) - Poshmark listing ID.
- **url** (string) - Canonical Poshmark listing URL.
- **title** (string) - Listing title.
- **soldPrice** (number) - Sale price in USD.
- **originalPrice** (number) - Original listing price in USD.
- **brand** (string) - Brand name.
- **size** (string) - Size label.
- **nwt** (boolean) - New With Tags flag.
- **likesCount** (number) - Number of likes.
- **sellerUsername** (string) - Poshmark seller username.
- **thumbnailUrl** (string) - Listing thumbnail URL.
- **scrapedAt** (string) - ISO 8601 timestamp.

#### Response Example
{
  "keyword": "louis vuitton neverfull",
  "page": 1,
  "totalItems": 48,
  "hasNextPage": true,
  "items": [
    {
      "listingId": "6478a1b2c3d4e5f6a7b8c9d0",
      "url": "https://poshmark.com/listing/Louis-Vuitton-Neverfull-6478a1b2c3d4e5f6a7b8c9d0",
      "title": "Louis Vuitton Neverfull MM Damier Ebene",
      "soldPrice": 1250,
      "originalPrice": 1960,
      "brand": "Louis Vuitton",
      "size": "OS",
      "nwt": false
    }
  ]
}
```

--------------------------------

### GET /v1/item/{itemId}

Source: https://sold-comps.com/docs

Look up any eBay listing by item ID and get the full detail page data: item specifics, all images, seller info, condition, shipping, location, category, ended date, and bid count. Works for both sold and active listings. Each call costs 1 request. Pass includeDescription=true to also fetch the seller's item description (~200ms extra latency, no additional quota cost).

```APIDOC
## GET /v1/item/{itemId}

### Description
Look up any eBay listing by item ID and get the full detail page data: item specifics, all images, seller info, condition, shipping, location, category, ended date, and bid count. Works for both sold and active listings. Each call costs 1 request. Pass `includeDescription=true` to also fetch the seller's item description (~200ms extra latency, no additional quota cost).

### Method
GET

### Endpoint
/v1/item/{itemId}

### Parameters
#### Path Parameters
- **itemId** (string) - Required - eBay item number (10-15 digits), e.g. 168647489856. Also accepts a full eBay item URL — the handler extracts the numeric ID.

#### Query Parameters
- **ebaySite** (string) - Optional - Default: `ebay.com`. eBay domain. Determines the currency of the returned price and shipping (e.g. USD on ebay.com, GBP on ebay.co.uk). Allowed values: `ebay.com`, `ebay.co.uk`, `ebay.de`, `ebay.fr`, `ebay.it`, `ebay.es`, `ebay.ca`, `ebay.com.au`.
- **includeDescription** (boolean) - Optional - Default: `false`. When true, fetches the seller's item description as sanitized plain text. Adds ~200ms latency, no additional quota cost.

### Request Example
```
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/item/168647489856"
```

### Response
#### Success Response (200)
- **itemId** (string) - eBay item number.
- **url** (string) - Canonical item URL.
- **title** (string | null) - Full listing title.
- **price** (string | null) - Current or sold price as a numeric string (e.g. "799.99").
- **currency** (string | null) - ISO currency code (e.g. "USD", "GBP"). Depends on ebaySite.
- **condition** (string | null) - Item condition label (e.g. "Pre-Owned", "Graded - PSA 10").
- **conditionDescription** (string | null) - Seller's condition notes, if provided.
- **ended** (boolean) - Whether the listing has ended (sold or expired).
- **endedDate** (string | null) - When the listing ended (e.g. "Sep 03, 2026 15:43:00 PDT"). Localized on non-English sites. null for active listings.
- **soldBanner** (string | null) - Sold banner text (e.g. "Item sold on Thu, Sep 3 at 3:43 PM"). English sites only; null on non-English sites and active listings.
- **bestOfferAccepted** (boolean) - true when the price shown is the asking price on a sold Best Offer listing, not the actual accepted amount (eBay never discloses it). false for auctions, Buy It Now sales, and active listings.
- **bidCount** (number | null) - Number of bids on auction listings. null for Buy It Now / Best Offer.
- **itemSpecifics** (Record<string, string>) - All item specifics as key-value pairs (e.g. {"Brand": "Apple", "Model": "iPhone 15 Pro", "Storage Capacity": "256 GB"}). Typically 10-30 fields per listing.
- **images** (string[]) - All listing image URLs at full resolution (1600px). Primary image first.
- **seller** (object | null) - Seller details: username (string), feedbackPercent (number, e.g. 99.8), itemsSold (string — localized, e.g. "4.7K items sold" on English sites, "88 Artikel verkauft" on ebay.de), joinedDate (string — localized, e.g. "Joined Jun 2026" on English sites, "Mitglied seit Jun 2026" on ebay.de).
- **shipping** (string | null) - Shipping cost text (e.g. "Free shipping", "US $9.99").
- **location** (string | null) - Item location (e.g. "San Jose, California, United States").
- **returnPolicy** (string | null) - Return policy text.
- **description** (string | null) - Seller's item description as plain text. Only present when includeDescription=true.
- **categoryPath** (string | null) - Breadcrumb path (e.g. "Cell Phones & Accessories > Cell Phones & Smartphones").
- **categoryId** (string | null) - Leaf category ID from the breadcrumb.
- **scrapedAt** (string) - ISO 8601 timestamp of when the data was fetched.

#### Response Example
```
{
  "itemId": "168647489856",
  "url": "https://www.ebay.com/itm/168647489856",
  "title": "2022 Pokemon Card 2022 S-Chinese Mimikyu CSM1.5C 014/060 Grade 10",
  "price": "4.99",
  "currency": "USD",
  "condition": "Graded - Other 10",
  "conditionDescription": null,
  "ended": true,
  "endedDate": "Sep 03, 2026 15:43:00 PDT",
  "soldBanner": "Item sold on Thu, Sep 3 at 3:43 PM",
  "bestOfferAccepted": false,
  "bidCount": 1,
  "itemSpecifics": {
    "Condition": "Graded - Other 10: Professionally graded",
    "Game": "Pokémon TCG",
    "Language": "Chinese",
    "Manufacturer": "The Pokémon Company",
    "Card Type": "Pokémon",
    "Finish": "Holo",
    "Card Size": "Standard",
    "Material": "Card Stock",
    "Vintage": "No",
    "Country of Origin": "China"
  },
  "images": [
    "https://i.ebayimg.com/images/g/PWcAAeSwRYJqdpUE/s-l1600.jpg",
    "https://i.ebayimg.com/images/g/EaMAAeSwYPFqdpPo/s-l1600.jpg"
  ],
  "seller": {
    "username": "ptcg-Pokémon",
    "feedbackPercent": 100,
    "itemsSold": "4.7K items sold",
    "joinedDate": "Joined Jun 2026"
  },
  "shipping": "US $9.99",
  "location": "Fuzhou City, Fujian, China"
}
```
```

--------------------------------

### GET /v1/mercari

Source: https://sold-comps.com/docs

Search Mercari listings (Beta). Returns one page of real Mercari listing data for a given keyword, normalized to a stable schema (price in dollars, condition labels, direct image URLs). Returns up to 100 items per page. Same auth and middleware stack as the eBay endpoints — rate limited per plan, monthly quota enforced per billing period. Each page costs 1 quota slot. Supports both sold and active listings via the `sold` parameter. This endpoint is in beta and may return errors under heavy load. Failed requests are not charged against your quota.

```APIDOC
## GET /v1/mercari

### Description
Search Mercari listings (Beta). Returns one page of real Mercari listing data for a given keyword, normalized to a stable schema (price in dollars, condition labels, direct image URLs). Returns up to 100 items per page. Same auth and middleware stack as the eBay endpoints — rate limited per plan, monthly quota enforced per billing period. Each page costs 1 quota slot. Supports both sold and active listings via the `sold` parameter. This endpoint is in beta and may return errors under heavy load. Failed requests are not charged against your quota.

### Method
GET

### Endpoint
/v1/mercari

### Parameters
#### Query Parameters
- **keyword** (string) - Required - Mercari search term.
- **page** (integer) - Optional - Default: `1`. Page number. Maps to offset = (page - 1) * count. Increment until hasNextPage is false.
- **count** (integer, 1–100) - Optional - Default: `100`. Items per page (max 100).
- **sortOrder** (enum) - Optional - Default: `bestMatch`. Sort order for results. Allowed values: `bestMatch`, `newest`, `lowestPrice`, `highestPrice`, `mostPopular`.
- **minPrice** (number) - Optional - Minimum price filter in dollars.
- **maxPrice** (number) - Optional - Maximum price filter in dollars.
- **itemCondition** (enum) - Optional - Default: `any`. Condition filter. Allowed values: `any`, `new`, `likeNew`, `good`, `fair`, `poor`.
- **categoryId** (string) - Optional - Mercari category ID.
- **brandId** (string) - Optional - Mercari brand ID.
- **sold** (boolean) - Optional - Default: `true`. true = sold listings (default), false = active/currently-listed items.

### Request Example
```
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/mercari?keyword=pokemon+cards&count=10&sortOrder=newest"
```

### Response
#### Success Response (200)
- **keyword** (string) - The search keyword.
- **page** (integer) - Current page number.
- **count** (integer) - Number of items returned.
- **totalResults** (integer) - Total number of results.
- **totalItems** (integer) - Total items in this page.
- **hasNextPage** (boolean) - Whether more pages exist.
- **items** (array) - List of listing items.
  - **itemId** (string) - Mercari item ID (e.g. "m19578215278").
  - **url** (string) - Canonical Mercari listing URL.
  - **title** (string) - Listing title.
  - **price** (string) - Price in dollars as a string with 2 decimal places (e.g. "25.00").
  - **currency** (string) - Always "USD" (Mercari US is USD-only).
  - **originalPrice** (string | null) - Pre-discount price. null when same as price.
  - **condition** (string | null) - "New", "Like New", "Good", "Fair", or "Poor".
  - **conditionId** (number | null) - Numeric condition ID (1–5).
  - **status** (string) - "sold" or "active".
  - **imageUrl** (string | null) - Full-resolution CDN image URL.
  - **thumbnailUrl** (string | null) - 200×200 thumbnail URL.
  - **sellerId** (string | null) - Numeric seller ID as string.
  - **brand** (string | null) - Brand name (e.g. "Pokemon").
  - **categoryId** (number | null) - Leaf category numeric ID.
  - **categoryName** (string | null) - Leaf category label.
  - **marketplace** (string) - Always "mercari".
- **marketplace** (string) - Always "mercari".
- **scrapedAt** (string) - Timestamp of scraping.

#### Response Example
```
{
  "keyword": "pokemon cards",
  "page": 1,
  "count": 10,
  "totalResults": 5844,
  "totalItems": 10,
  "hasNextPage": true,
  "items": [
    {
      "itemId": "m19578215278",
      "url": "https://www.mercari.com/us/item/m19578215278/",
      "title": "Pokemon TCG Charizard VMAX Rainbow 074/073 PSA 10",
      "price": "185.00",
      "currency": "USD",
      "originalPrice": null,
      "condition": "Like New",
      "conditionId": 2,
      "status": "sold",
      "imageUrl": "https://static.mercdn.net/item/detail/orig/photos/m19578215278_1.jpg",
      "thumbnailUrl": "https://static.mercdn.net/c!/w=200/thumb/photos/m19578215278_1.jpg",
      "sellerId": "472918365",
      "brand": "Pokemon",
      "categoryId": 753,
      "categoryName": "Trading Cards",
      "marketplace": "mercari"
    }
  ],
  "marketplace": "mercari",
  "scrapedAt": "2026-09-02T14:30:00.000Z"
}
```
```

--------------------------------

### GET /v1/scrape/category

Source: https://sold-comps.com/docs

Scrapes eBay sold listings by category. Requires bearer token authentication.

```APIDOC
## GET /v1/scrape/category

### Description
Scrapes eBay sold listings by category. Requires bearer token authentication.

### Method
GET

### Endpoint
https://api.sold-comps.com/v1/scrape/category

### Parameters
#### Query Parameters
- **category** (string) - Required - The eBay category identifier.
- **count** (integer) - Optional - Number of results to return (default 40, up to 200 with cookies).

### Request Example
```
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/scrape/category?category=9355&count=10"
```

### Response
#### Success Response (200)
- **listings** (array) - List of sold listings with price, condition, date, seller.

#### Response Example
```json
{
  "listings": [
    {
      "price": 49.99,
      "condition": "Used",
      "date": "2024-02-01",
      "seller": "seller456"
    }
  ]
}
```
```

--------------------------------

### GET /v1/scrape/max/results/:jobId

Source: https://sold-comps.com/docs

Poll for the progress or final results of a specific Max Mode job.

```APIDOC
## GET /v1/scrape/max/results/:jobId

### Description
Returns progress while the job is running, or a summary + delivery info once terminal. Recommended poll interval is 5 seconds.

### Method
GET

### Endpoint
/v1/scrape/max/results/:jobId

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The unique identifier for the job.
```

--------------------------------

### Scrape sold listings with curl

Source: https://sold-comps.com/docs

Sends a GET request to the /v1/scrape endpoint with the keyword, site, page, count, and sort order. Requires a bearer token; replace sc_YOUR_KEY_HERE with your actual key.

```bash
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/scrape\
?keyword=iphone+15+pro\
&ebaySite=ebay.com\
&page=1\
&count=40\
&sortOrder=endedRecently"
```

--------------------------------

### GET /api/bulk-search

Source: https://sold-comps.com/docs

Bulk search endpoint for eBay sold listings. Requires bearer token authentication.

```APIDOC
## GET /api/bulk-search

### Description
Bulk search endpoint for eBay sold listings. Requires bearer token authentication.

### Method
GET

### Endpoint
https://api.sold-comps.com/api/bulk-search

### Parameters
#### Query Parameters
- **keywords** (string) - Required - Comma-separated list of search keywords.
- **count** (integer) - Optional - Number of results per keyword (default 40, up to 200 with cookies).

### Request Example
```
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/api/bulk-search?keywords=iphone,samsung&count=10"
```

### Response
#### Success Response (200)
- **results** (object) - Map of keyword to listings array.

#### Response Example
```json
{
  "results": {
    "iphone": [
      {
        "price": 899.99,
        "condition": "New",
        "date": "2024-01-15",
        "seller": "seller123"
      }
    ],
    "samsung": [
      {
        "price": 699.99,
        "condition": "Used",
        "date": "2024-02-20",
        "seller": "seller456"
      }
    ]
  }
}
```
```

--------------------------------

### aspectFilter JSON examples for eBay facet filtering

Source: https://sold-comps.com/docs

Use these JSON objects as the aspectFilter query parameter to narrow results by eBay sidebar facets. The first example filters by brand and storage capacity; the second filters trading cards by grade and manufacturer. Multi-select values use a pipe separator, e.g. {"Grade":"9|10"}.

```json
aspectFilter={"Brand":"Apple","Storage Capacity":"256 GB"}
```

```json
aspectFilter={"Professional Grader":"PSA","Grade":"10","Manufacturer":"Topps"}
```

--------------------------------

### Search Mercari listings with curl and sample JSON response

Source: https://sold-comps.com/docs

Use this request to search Mercari listings (beta) for a keyword. The response shows a sample item with fields like itemId, price, condition, and status. The endpoint returns up to 100 items per page and supports sold/active via the sold parameter.

```bash
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/mercari\
?keyword=pokemon+cards\
&count=10\
&sortOrder=newest"
```

```json
{
  "keyword": "pokemon cards",
  "page": 1,
  "count": 10,
  "totalResults": 5844,
  "totalItems": 10,
  "hasNextPage": true,
  "items": [
    {
      "itemId": "m19578215278",
      "url": "https://www.mercari.com/us/item/m19578215278/",
      "title": "Pokemon TCG Charizard VMAX Rainbow 074/073 PSA 10",
      "price": "185.00",
      "currency": "USD",
      "originalPrice": null,
      "condition": "Like New",
      "conditionId": 2,
      "status": "sold",
      "imageUrl": "https://static.mercdn.net/item/detail/orig/photos/m19578215278_1.jpg",
      "thumbnailUrl": "https://static.mercdn.net/c!/w=200/thumb/photos/m19578215278_1.jpg",
      "sellerId": "472918365",
      "brand": "Pokemon",
      "categoryId": 753,
      "categoryName": "Trading Cards",
      "marketplace": "mercari"
    }
  ],
  "marketplace": "mercari",
  "scrapedAt": "2026-09-02T14:30:00.000Z"
}
```

--------------------------------

### TCGPlayer Sales History API Response

Source: https://sold-comps.com/docs

Example response body for a successful TCGPlayer sales history request.

```json
{
  "productId": 274439,
  "totalResults": 5,
  "hasNextPage": false,
  "items": [
    {
      "price": 4.66,
      "shippingPrice": 4.90,
      "totalPrice": 9.56,
      "condition": "Near Mint",
      "variant": "Holofoil",
      "language": "English",
      "quantity": 1,
      "soldDate": "2026-09-07T18:32:25.75+00:00",
      "listingType": "ListingWithoutPhotos",
      "marketplace": "tcgplayer"
    }
  ],
  "marketplace": "tcgplayer",
  "scrapedAt": "2026-09-07T20:00:00.000Z"
}
```

--------------------------------

### Credit-only mode with X-Credit-Source header

Source: https://sold-comps.com/docs

curl command to use credit-only mode by passing X-Credit-Source: credits header.

```bash
curl -H "Authorization: Bearer sc_YOUR_KEY" \
     -H "X-Credit-Source: credits" \
     "https://api.sold-comps.com/v1/scrape?keyword=iphone"
```

--------------------------------

### TCGPlayer Sales History JSON Response

Source: https://sold-comps.com/docs

Example of the JSON structure returned by the TCGPlayer sales history endpoint.

```json
{
  "number": "010/078",
  "setCode": "PGO",
  "setId": 3121,
  "marketPrice": 3.68,
  "lowestPrice": 0.99,
  "lowestListingPrice": 1.15,
  "lowestPriceWithShipping": 2.48,
  "medianPrice": 4.39,
  "totalListings": 88,
  "foilOnly": false,
  "imageUrl": null,
  "url": "https://www.tcgplayer.com/product/274439",
  "productLine": "Pokemon",
  "marketplace": "tcgplayer",
  "listings": [
    {
      "price": 1.15,
      "shippingPrice": 1.49,
      "totalPrice": 2.64,
      "condition": "Lightly Played",
      "printing": "Normal",
      "language": "English",
      "quantity": 3,
      "sellerName": "CardShop TCG",
      "sellerRating": 99.8,
      "verifiedSeller": true,
      "directSeller": false
    }
  ]
}
  ],
  "marketplace": "tcgplayer",
  "scrapedAt": "2026-09-07T20:00:00.000Z"
}
```

--------------------------------

### GET /v1/scrape/max/:jobId/download.csv

Source: https://sold-comps.com/docs

Downloads the full scraping result as a CSV file. Authenticated with a signed token in the query parameter.

```APIDOC
## GET /v1/scrape/max/:jobId/download.csv

### Description
Streams the full result as CSV. Authenticated with a signed token in the `?token=` query parameter, not a Bearer header — the URL is safe to share in email. Tokens expire 24 hours after the job completes. The download URL is returned at the top level of the poll response as `downloadUrl` (when `resultType=download`) or attached directly to completion emails. Do not append your API key — the signed token is the auth. CSV columns: every field on the per-item response, one row per listing.

### Method
GET

### Endpoint
/v1/scrape/max/:jobId/download.csv

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The unique identifier of the scraping job.

#### Query Parameters
- **token** (string) - Required - Signed token for authentication, expires 24 hours after job completion.

### Request Example
```
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  https://api.sold-comps.com/v1/scrape/max/8c2f1a3e-3b54-4f6b-9c2a-1d6e2b9a0d31/download.csv?token=YOUR_SIGNED_TOKEN
```

### Response
#### Success Response (200)
Streams the full result as CSV. CSV columns: every field on the per-item response, one row per listing.
```

--------------------------------

### Bulk Search Response

Source: https://sold-comps.com/docs

Example of the server-sent event stream returned by the bulk-search endpoint, including progress updates, individual keyword results, and a final completion event.

```text
event: progress
data: {"keyword":"iphone 15 pro","status":"processing"}

event: result
data: {"keyword":"iphone 15 pro","status":"completed","totalItems":142,"totalResults":"14,000+","hasNextPage":true,"autoSelectedCategory":null,"scrapedCount":142,"items":[{"itemId":"123456789","title":"Apple iPhone 15 Pro 256GB","soldPrice":"899.99","soldCurrency":"USD","condition":"Pre-Owned","endedAt":"2026-08-15"}]}

event: progress
data: {"keyword":"macbook air m2","status":"processing"}

event: result
data: {"keyword":"macbook air m2","status":"completed","totalItems":98,"totalResults":"5,200+","hasNextPage":true,"autoSelectedCategory":null,"items":[...]}

event: complete
data: {"total":3,"succeeded":3,"failed":0}
```