# Costco Scraper — Product Search, Details & Price API (`sian.agency/costco-data-scraper`) Actor

Scrape Costco.com at scale: keyword product search and full product details by item number. Real-time sale/list/per-unit prices, ratings, stock, brand and SKUs in one clean JSON dataset. API-backed and reliable — built for price monitoring, price tracking and catalog enrichment.

- **URL**: https://apify.com/sian.agency/costco-data-scraper.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** E-commerce, Business, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.90 / 1,000 search result rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Costco Scraper — Product Search, Details & Price API 🛒

[![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Amazon Influencer & Deals](https://img.shields.io/badge/Store-Amazon%20Influencer%20%26%20Deals-FF9900)](https://apify.com/sian.agency/amazon-influencer-deals-scraper?fpr=sian) [![Taobao & Tmall](https://img.shields.io/badge/Store-Taobao%20%26%20Tmall-FF4F00)](https://apify.com/sian.agency/taobao-tmall-product-scraper?fpr=sian) [![TikTok Shop](https://img.shields.io/badge/Store-TikTok%20Shop-25F4EE)](https://apify.com/sian.agency/tiktok-shop-scraper?fpr=sian)

#### 🎉 Real-time Costco product data — search any keyword and pull full product details by item number, into one clean JSON dataset
##### Built for price monitoring, price tracking, and catalog enrichment teams who need reliable Costco data without running a brittle browser scraper

---

### 📋 Overview

**Pull Costco product data the reliable way.** This Costco Scraper extracts keyword search results and full product details from Costco.com (and Costco.ca) into clean, query-ready JSON — no browser automation, no proxies, no captchas to manage on your side.

**Why teams choose this Costco Scraper:**
- ✅ **API-backed reliability**: real-time data source, not a fragile HTML scraper that breaks when Costco changes its layout — structured rows every run.
- ⚡ **Two modes, one dataset**: keyword **Product Search** (~24 products/page) and deep **Product Details** by item number — pick one per run.
- 🎯 **Rich, structured fields**: sale price, list price, per-unit price, ratings, stock status, brand (incl. Kirkland Signature), program eligibility, category path, marketing features, UPC/SKUs and image galleries.
- 💰 **Honest pay-per-result pricing**: charged only for successful products, with a transparent low Actor-start fee — no inflated start charges, no monthly subscription.
- 💎 **US + Canada**: query costco.com or costco.ca with a single `country` switch.
- ✨ **Clean camelCase output**: curated aliases plus the raw upstream fields spread alongside, so nothing is lost.

---

### ✨ Features

- 🔍 **Product Search**: search Costco by any keyword and paginate through results (~24 products per page).
- 📦 **Product Details**: fetch one product's full record by its Costco item number.
- 💲 **Full pricing**: sale price, list price, minimum/maximum price, and per-unit price with currency.
- ⭐ **Ratings & reviews count**: average rating and total review count per product.
- 📦 **Availability intel**: in-stock flag, stock status, delivery status, backorder flag, and fulfillment min/max quantities.
- 🏷️ **Membership signals**: member-only flag and program eligibility (ShipIt, 2-Day Delivery, In-Warehouse, Warehouse Delivery).
- 🧾 **Catalog data**: brand, category path, item class, department/category, marketing features and statement, UPC/SKUs.
- 🖼️ **Images**: primary image plus the full image gallery, with HTTPS-normalized URLs.
- 🌍 **US + Canada**: switch between costco.com and costco.ca.
- 📄 **Auto-pagination**: search stops automatically when the data source reports no more results.

---

### 🎬 Quick Start

Pick an operation, give it a query (search) or an item number (details), and run. Each run produces one clean dataset matching the chosen mode. Results export to JSON, CSV, or Excel from the Apify dataset.

```bash
curl -X POST "https://api.apify.com/v2/acts/sian.agency~costco-data-scraper/runs?token=YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"operation": "search", "query": "paper towels", "maxPages": 2}'
````

***

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Choose your operation

Select **Product Search** to discover products by keyword, or **Product Details** to fetch a single product by its Costco item number.

#### Step 2: Provide your input

For search, enter a query like `air fryer`. For details, enter an item number like `512599`. Optionally set the country (US/CA) and max pages.

#### Step 3: Run and export

Start the run and watch the dataset fill with clean rows. Export to JSON, CSV, or Excel, or pull results via the Apify API.

**That's it! In a couple of minutes, you'll have:**

- A structured dataset of Costco products
- Real-time prices, ratings, stock status, brand and SKUs
- Clean fields ready for price-monitoring or catalog workflows

> ⏱️ **Note:** Costco is a slow data source. Each page can take **1–2 minutes** to return — large page counts may run long. The actor retries transient failures automatically.

***

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `operation` | string | Yes | `search` or `productDetails` — pick one per run |
| `query` | string | For `search` | Costco product search query (e.g. `paper towels`) |
| `productId` | string | For `productDetails` | Costco item number (e.g. `512599`) |
| `country` | string | No | `US` (costco.com, default) or `CA` (costco.ca) |
| `language` | string | No | Result language, e.g. `en-US` (default) or `fr-CA` |
| `maxPages` | integer | No | Pages to fetch for search (default 5, max 50) |

**Search example:**

```json
{
  "operation": "search",
  "query": "kirkland signature olive oil",
  "country": "US",
  "maxPages": 3
}
```

**Product details example:**

```json
{
  "operation": "productDetails",
  "productId": "512599",
  "country": "US"
}
```

***

### 📤 Output

Results are saved to the Apify dataset with **40+ structured fields** per product, including:

| Field | Type | Description |
|-------|------|-------------|
| `itemNumber` | string | Costco item number (primary id) |
| `itemName` | string | Product name |
| `brand` | array | Brand(s), e.g. `["Kirkland Signature"]` |
| `salePrice` | number | Current sale price |
| `listPrice` | number | List price |
| `pricePerUnit` | number | Price per unit |
| `currency` | string | Currency code (e.g. `USD`) |
| `rating` | number | Average rating |
| `reviewCount` | integer | Total review count |
| `memberOnly` | boolean | Member-only product flag |
| `inStock` | boolean | In-stock flag |
| `stockStatus` | string | e.g. `in stock` |
| `programEligibility` | array | Fulfillment programs (ShipIt, 2-Day, In-Warehouse…) |
| `categoryPath` | array | Category breadcrumb paths |
| `skus` | array | Manufacturing UPC/SKUs |
| `image` | string | Primary image URL |
| `images` | array | Full image gallery |
| `productUrl` | string | Costco product URL |

**Example row (truncated):**

```json
{
  "_operation": "search",
  "status": "success",
  "itemNumber": "512599",
  "itemName": "Kirkland Signature Paper Towels, 2-Ply, 160 Sheets, 12 Rolls",
  "brand": ["Kirkland Signature"],
  "salePrice": 23.99,
  "listPrice": 23.99,
  "pricePerUnit": 23.99,
  "currency": "USD",
  "rating": 0,
  "reviewCount": 0,
  "memberOnly": false,
  "inStock": true,
  "stockStatus": "in stock",
  "programEligibility": ["ShipIt", "2DayDelivery", "InWarehouse"],
  "categoryPath": ["/grocery-household.html", "/paper-towels-napkins.html"],
  "skus": ["096619880676"],
  "image": "https://bfasset.costco-static.com/.../512599-847__1"
}
```

Filter the dataset by `_operation` (search / productDetails) or `status` (success / error) to split or clean rows.

***

### 💼 Use Cases & Examples

#### 1. Price & Assortment Monitoring

**Retail analysts tracking Costco prices across a category.**

**Input:** Product Search with a category query, scheduled daily
**Output:** Sale price, list price, per-unit price, and stock status per product
**Use:** Diff the dataset between runs to catch price moves, rollbacks, and new SKUs.

#### 2. Costco Price Tracking

**E-commerce operators following specific item prices over time.**

**Input:** Product Details for a known item number, run on a schedule
**Output:** Current sale/list price, member-only flag, and availability
**Use:** Power a price-tracker dashboard or alerting workflow on price drops.

#### 3. Competitor Catalog Mapping

**Brand managers benchmarking against Costco's assortment.**

**Input:** Product Search across your product segments
**Output:** Brand presence (incl. Kirkland Signature), category coverage, and positioning
**Use:** Map Costco's catalog against your own to find gaps and overlaps.

#### 4. Product Catalog Enrichment

**Data teams building a structured product database.**

**Input:** Product Details for a list of item numbers
**Output:** Marketing features, program eligibility, category path, UPC/SKUs, image gallery
**Use:** Enrich your own catalog with clean, query-ready Costco attributes.

#### 5. Membership & Availability Intelligence

**Operations teams analyzing Costco availability at scale.**

**Input:** Product Search or Details with stock fields
**Output:** Member-only flags, in-stock status, delivery status, fulfillment programs
**Use:** Understand membership-gated pricing and availability patterns across products.

#### 6. Market Research & Pricing Studies

**Researchers studying warehouse-club pricing.**

**Input:** Broad keyword searches across categories
**Output:** Price, per-unit price, brand, and rating data in bulk
**Use:** Build pricing datasets for analysis, modeling, or reporting.

***

### 🔗 Integration Examples

#### JavaScript/Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/costco-data-scraper').call({
  operation: 'search',
  query: 'air fryer',
  maxPages: 2,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/costco-data-scraper').call(
    run_input={'operation': 'productDetails', 'productId': '512599'}
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item)
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~costco-data-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"operation": "search", "query": "olive oil", "maxPages": 1}'
```

#### Automation Workflows (N8N / Zapier / Make)

1. **Trigger**: Schedule (e.g. daily price check) or webhook
2. **HTTP Request**: Call the actor API with your operation + input
3. **Process**: Handle the JSON dataset rows
4. **Action**: Save to a database, diff prices, or send alerts

***

### 📊 Performance & Pricing

#### FREE Tier (Try It Now)

- Run both operations with full feature access — same fields, same quality
- No credit card required
- Perfect for testing and small price checks

#### PAID Tier (Production Ready)

- Scale up search pagination and bulk item lookups
- Pay-per-result: only charged for successful products
- Transparent, low Actor-start fee — no inflated start charges, no subscription

💰 **Honest pay-per-result pricing** — you pay for the Costco products you actually get, not a flat monthly fee.

🔗 [View current pricing](https://apify.com/sian.agency/costco-data-scraper?fpr=sian)

***

### ❓ Frequently Asked Questions

**Q: What can I scrape from Costco?**
A: Two modes — keyword **Product Search** (paginated product listings) and **Product Details** by Costco item number. Each returns prices, ratings, stock, brand, program eligibility, category path, and SKUs.

**Q: Why is a run slow sometimes?**
A: Costco is a slow data source — each page can take 1–2 minutes to return. The actor retries transient failures automatically and stops pagination when the data source reports no more results.

**Q: Does it support Costco Canada?**
A: Yes. Set `country` to `CA` for costco.ca (default is `US` for costco.com).

**Q: How do I find an item number?**
A: Run Product Search first — every result row includes `itemNumber`. It also appears in Costco product URLs.

**Q: Does it scrape customer review text?**
A: No. The data source provides aggregate ratings and review counts, but not individual review text. We only expose what the source reliably returns.

**Q: What output formats are available?**
A: JSON, CSV, and Excel — export directly from the Apify dataset, or pull results via the Apify API.

**Q: Is this legal?**
A: We only extract publicly available product data. See the [legal section](#is-it-legal-to-scrape-data) below.

***

### 🐛 Troubleshooting

**A run returns an error row instead of products**

- The data source may have hit a transient hiccup — re-run it; the actor already retries automatically.
- For Product Details, double-check the item number is valid (run Product Search to confirm it).

**Search returns fewer pages than `maxPages`**

- This is expected — pagination stops automatically when Costco reports no more results for your query.

**A run takes several minutes**

- Costco is a slow source (1–2 minutes per page). Start with `maxPages: 1–3` to preview before scaling up.

**No results for a query**

- Try a broader or differently-worded query; very specific phrases can return zero matches.

***

### ⚖️ Is it legal to scrape data?

Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what has been chosen to be shared publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe.

However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/).

***

### 🤝 Support

[![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi)

**Join our active support community**

- For issues or questions, open an issue in the actor's Issues tab
- Check the [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools
- 📧 <apify@sian-agency.online>

***

### ✨ More by SIÁN Agency

- [Amazon Influencer & Deals Scraper](https://apify.com/sian.agency/amazon-influencer-deals-scraper?fpr=sian) — Amazon search, products, deals & reviews
- [Taobao & Tmall Product Scraper](https://apify.com/sian.agency/taobao-tmall-product-scraper?fpr=sian) — Chinese e-commerce products & search
- [TikTok Shop Scraper](https://apify.com/sian.agency/tiktok-shop-scraper?fpr=sian) — TikTok Shop products, search & sellers
- [Browse all SIÁN actors →](https://apify.com/sian.agency?fpr=sian)

***

### ⚠️ Trademark Disclaimer

This actor is an independent tool and is **not affiliated with, endorsed by, or sponsored by Costco Wholesale Corporation.** "Costco", "Kirkland Signature", and related marks are trademarks of their respective owners and are used here only to describe the data this tool helps you collect. Use this actor responsibly and in compliance with applicable laws, Costco's terms of service, and data-protection regulations (including GDPR and CCPA where applicable). You are responsible for how you use the data you extract.

### Legal

Scrape only publicly available data and use it lawfully. For guidance on ethical and compliant web scraping, see Apify's [guide to web scraping legality](https://blog.apify.com/is-web-scraping-legal/). Do not collect personal data in violation of GDPR, CCPA, or other applicable privacy laws.

***

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

# Actor input Schema

## `operation` (type: `string`):

🎯 **PICK ONE OPERATION PER RUN.** Each run produces one clean dataset matching the chosen mode.

- **🔍 Product Search** — keyword search across Costco products, paginated (~24 results/page)
- **📦 Product Details** — full details of a single product by its Costco item number (price, ratings, stock, brand, marketing features, SKUs)

💡 **TIP:** Run Product Search to discover item numbers, then drill into Product Details per item.

## `query` (type: `string`):

🔍 **Required for `Product Search` operation.**

Any Costco product search query.

- `paper towels`
- `kirkland signature olive oil`
- `air fryer`

💡 **TIP:** Long-tail queries return higher-relevance results.

⚠️ **Ignored** for Product Details.

## `productId` (type: `string`):

📦 **Required for `Product Details` operation.**

The Costco product / item number — the numeric ID that identifies a product.

- `512599`

It appears as the `itemNumber` field in any Product Search result row, and in Costco product URLs: `https://www.costco.com/.product.{itemNumber}.html`.

💡 **TIP:** Run `Product Search` first to discover item numbers, then loop through Product Details per item.

⚠️ **Ignored** for Product Search.

## `country` (type: `string`):

🌍 Which Costco country / domain to query. `US` = costco.com (default), `CA` = costco.ca.

## `language` (type: `string`):

Result language. Defaults to the major language for the chosen country (e.g. `en-US` for US). Examples: `en-US`, `fr-CA`.

## `maxPages` (type: `integer`):

📄 **Applies to `Product Search` only** (~24 products per page). Ignored for Product Details.

💡 **TIP:** Start small (1–3 pages) to preview results before scaling up. Pagination stops automatically when the data source reports no more results.

⚠️ Hard cap: 50 pages to prevent runaway runs.

⏱️ **Note:** Costco responses can take 1–2 minutes per page — large page counts may run long.

## Actor input object example

```json
{
  "operation": "search",
  "query": "paper towels",
  "productId": "512599",
  "country": "US",
  "language": "en-US",
  "maxPages": 5
}
```

# Actor output Schema

## `output` (type: `string`):

Per-row results — one flat row per Costco product with curated camelCase aliases (itemNumber, itemName, salePrice, listPrice, pricePerUnit, rating, reviewCount, brand, programEligibility, skus, images, …) plus the raw upstream fields spread alongside.

## `report` (type: `string`):

HTML report with run status, success/error row counts, success rate, pages fetched, duration, and the inputs used — written even on fatal crash.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "paper towels",
    "productId": "512599"
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/costco-data-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "paper towels",
    "productId": "512599",
}

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/costco-data-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "paper towels",
  "productId": "512599"
}' |
apify call sian.agency/costco-data-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=sian.agency/costco-data-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Costco Scraper — Product Search, Details & Price API",
        "description": "Scrape Costco.com at scale: keyword product search and full product details by item number. Real-time sale/list/per-unit prices, ratings, stock, brand and SKUs in one clean JSON dataset. API-backed and reliable — built for price monitoring, price tracking and catalog enrichment.",
        "version": "1.0",
        "x-build-id": "5AmIBzmb6q7V8Gn6k"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/sian.agency~costco-data-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-sian.agency-costco-data-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/sian.agency~costco-data-scraper/runs": {
            "post": {
                "operationId": "runs-sync-sian.agency-costco-data-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/sian.agency~costco-data-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-sian.agency-costco-data-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "operation"
                ],
                "properties": {
                    "operation": {
                        "title": "🎯 Operation — what do you want to scrape?",
                        "enum": [
                            "search",
                            "productDetails"
                        ],
                        "type": "string",
                        "description": "🎯 **PICK ONE OPERATION PER RUN.** Each run produces one clean dataset matching the chosen mode.\n\n- **🔍 Product Search** — keyword search across Costco products, paginated (~24 results/page)\n- **📦 Product Details** — full details of a single product by its Costco item number (price, ratings, stock, brand, marketing features, SKUs)\n\n💡 **TIP:** Run Product Search to discover item numbers, then drill into Product Details per item.",
                        "default": "search"
                    },
                    "query": {
                        "title": "🔍 Search Query (for Product Search)",
                        "type": "string",
                        "description": "🔍 **Required for `Product Search` operation.**\n\nAny Costco product search query.\n- `paper towels`\n- `kirkland signature olive oil`\n- `air fryer`\n\n💡 **TIP:** Long-tail queries return higher-relevance results.\n\n⚠️ **Ignored** for Product Details."
                    },
                    "productId": {
                        "title": "📦 Item Number (for Product Details)",
                        "type": "string",
                        "description": "📦 **Required for `Product Details` operation.**\n\nThe Costco product / item number — the numeric ID that identifies a product.\n- `512599`\n\nIt appears as the `itemNumber` field in any Product Search result row, and in Costco product URLs: `https://www.costco.com/.product.{itemNumber}.html`.\n\n💡 **TIP:** Run `Product Search` first to discover item numbers, then loop through Product Details per item.\n\n⚠️ **Ignored** for Product Search."
                    },
                    "country": {
                        "title": "🌍 Country (Costco domain)",
                        "enum": [
                            "US",
                            "CA"
                        ],
                        "type": "string",
                        "description": "🌍 Which Costco country / domain to query. `US` = costco.com (default), `CA` = costco.ca.",
                        "default": "US"
                    },
                    "language": {
                        "title": "🗣️ Language",
                        "type": "string",
                        "description": "Result language. Defaults to the major language for the chosen country (e.g. `en-US` for US). Examples: `en-US`, `fr-CA`.",
                        "default": "en-US"
                    },
                    "maxPages": {
                        "title": "📄 Max pages to fetch",
                        "minimum": 1,
                        "maximum": 50,
                        "type": "integer",
                        "description": "📄 **Applies to `Product Search` only** (~24 products per page). Ignored for Product Details.\n\n💡 **TIP:** Start small (1–3 pages) to preview results before scaling up. Pagination stops automatically when the data source reports no more results.\n\n⚠️ Hard cap: 50 pages to prevent runaway runs.\n\n⏱️ **Note:** Costco responses can take 1–2 minutes per page — large page counts may run long.",
                        "default": 5
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```