Docs menu

Costco API endpoint

Costco search API

Returns public Costco products matching a text query and/or a category slug: title, brand, model, image, and rating for each result. GDX is primary; if GDX is blocked, query-only searches may return explicitly partial product-sitemap results.

GETapiKey3 credits/requestCostcocostco.searchResponseDoc/costco/search

Endpoint facts

Method: GET
API path: /costco/search
Auth: apiKey
Credits: 3 credits/request
Charged on: Successful 2xx responses only
Platform: Costco
Response schema: #/definitions/costco.searchResponseDoc

Costco Scraper API Try Costco search API in Playground Costco API documentation

How this endpoint behaves

Query parameters:

query (optional) — search text.
category (optional) — a Costco category slug, the last path segment of a category page URL (e.g. refrigerators from costco.com/refrigerators.html, or french-door-refrigerators for a subcategory).

At least one of query/category is required.

Notable response behavior:

Each result's id is usable directly as the id path parameter to /costco/product/{id}.
A missing query and category returns 400 before any upstream request is made.
When the GDX search service is blocked, query-only requests may use a partial fallback. In that response, source is product_sitemap and is_partial is true. The total_count then counts product URL slugs matching the query, not Costco's GDX result count, and the order follows Costco's product sitemap rather than GDX relevance. Other source values are not currently returned; source is omitted for complete GDX results.
The product-sitemap fallback does not handle category filters and does not return success when no product slug matches the query.
If GDX is blocked, text-only queries may fall back to actual products from Costco's public product sitemap, enriched from its product GraphQL API. Those responses include source: "product_sitemap" and is_partial: true. In that case total_count counts matching sitemap URL slugs, the product order follows the sitemap, and results may be fewer than Costco's GDX result set. This fallback is not used for category-filtered queries or when no sitemap product matches; those calls continue returning an upstream error.

Live monitoring

Monitored request: GET /costco/search?query=refrigerator
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 2.99 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /costco/search?query=refrigerator
Items in products: 24
Fields filled in every checked item: 7
Fields empty in some or all items: 2

Field	Filled in, of 24 checked	Values in the sample
id	24
url	24	costco.com
title	24	“LG 20 cu. ft. Top Freezer Refrigerator” and 23 other values
brand	24	Whirlpool (6), LG (5), Samsung (4) and 5 more
model	24	“LTCS20020V” and 23 other values
image_url	24	gdx-assets.costco.com and 1 other host
categories	24	median 3 entries
rating	23	3.03 to 4.55, median 4.09
rating_count	23	11 to 2,008, median 410

Request parameters

Parameter	Type	Required	Description	Example
query	string	No	Search text	refrigerator
category	string	No	Costco category slug, e.g. the last path segment of a category page URL	refrigerators
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/costco/search?query=coffee" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "refrigerator",
    "total_count": 381,
    "products": [
      {
        "id": "4000181299",
        "url": "https://www.costco.com/p/-/mora-18-cu-ft-top-freezer-refrigerator/4000181299",
        "title": "Mora 18 cu. ft. Top Freezer Refrigerator",
        "brand": "Mora",
        "model": "MRT180N6AWD",
        "image_url": "https://gdx-assets.costco.com/adobe/assets/urn:aaid:aem:9913a059-4644-4e07-a049-7f72f2e28b5c/as/1731564-847__1.avif",
        "categories": [
          "Appliances",
          "Appliances > Refrigerators",
          "Appliances > Refrigerators > Top Freezer Refrigerators"
        ],
        "rating": 4.2566,
        "rating_count": 491
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/costco.searchResponseDoc

Field	Type	Required	Enum	Example	Description
code	integer	No		200
data	costco.SearchResponse	No
data.category	string	No
data.is_partial	boolean	No			IsPartial is true when a fallback source cannot reproduce the complete Costco search result set.
data.products	array	No
data.products[].brand	string	No
data.products[].categories	array	No
data.products[].id	string	No
data.products[].image_url	string	No
data.products[].model	string	No
data.products[].rating	number	No
data.products[].rating_count	integer	No
data.products[].title	string	No
data.products[].url	string	No
data.query	string	No
data.source	string	No	product_sitemap		Source is omitted for complete GDX search results. product_sitemap identifies a degraded query-only fallback whose ordering and count are based on product URL slugs rather than Costco's search index.
data.total_count	integer	No
msg	string	No		OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/costco/search?query=coffee" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More Costco endpoint docs Costco Scraper API Costco categories API documentation Costco product API documentation Costco product availability API documentation Costco product reviews API documentation Costco warehouses API documentation

Open in Playground Back to group

Docs menu

Costco API endpoint

Costco search API

GETapiKey3 credits/requestCostcocostco.searchResponseDoc/costco/search

Endpoint facts

Method: GET
API path: /costco/search
Auth: apiKey
Credits: 3 credits/request
Charged on: Successful 2xx responses only
Platform: Costco
Response schema: #/definitions/costco.searchResponseDoc

Costco Scraper API Try Costco search API in Playground Costco API documentation

How this endpoint behaves

Query parameters:

query (optional) — search text.
category (optional) — a Costco category slug, the last path segment of a category page URL (e.g. refrigerators from costco.com/refrigerators.html, or french-door-refrigerators for a subcategory).

At least one of query/category is required.

Notable response behavior:

Each result's id is usable directly as the id path parameter to /costco/product/{id}.
A missing query and category returns 400 before any upstream request is made.
When the GDX search service is blocked, query-only requests may use a partial fallback. In that response, source is product_sitemap and is_partial is true. The total_count then counts product URL slugs matching the query, not Costco's GDX result count, and the order follows Costco's product sitemap rather than GDX relevance. Other source values are not currently returned; source is omitted for complete GDX results.
The product-sitemap fallback does not handle category filters and does not return success when no product slug matches the query.
If GDX is blocked, text-only queries may fall back to actual products from Costco's public product sitemap, enriched from its product GraphQL API. Those responses include source: "product_sitemap" and is_partial: true. In that case total_count counts matching sitemap URL slugs, the product order follows the sitemap, and results may be fewer than Costco's GDX result set. This fallback is not used for category-filtered queries or when no sitemap product matches; those calls continue returning an upstream error.

Live monitoring

Monitored request: GET /costco/search?query=refrigerator
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 2.99 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /costco/search?query=refrigerator
Items in products: 24
Fields filled in every checked item: 7
Fields empty in some or all items: 2

Field	Filled in, of 24 checked	Values in the sample
id	24
url	24	costco.com
title	24	“LG 20 cu. ft. Top Freezer Refrigerator” and 23 other values
brand	24	Whirlpool (6), LG (5), Samsung (4) and 5 more
model	24	“LTCS20020V” and 23 other values
image_url	24	gdx-assets.costco.com and 1 other host
categories	24	median 3 entries
rating	23	3.03 to 4.55, median 4.09
rating_count	23	11 to 2,008, median 410

Request parameters

Parameter	Type	Required	Description	Example
query	string	No	Search text	refrigerator
category	string	No	Costco category slug, e.g. the last path segment of a category page URL	refrigerators
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/costco/search?query=coffee" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "refrigerator",
    "total_count": 381,
    "products": [
      {
        "id": "4000181299",
        "url": "https://www.costco.com/p/-/mora-18-cu-ft-top-freezer-refrigerator/4000181299",
        "title": "Mora 18 cu. ft. Top Freezer Refrigerator",
        "brand": "Mora",
        "model": "MRT180N6AWD",
        "image_url": "https://gdx-assets.costco.com/adobe/assets/urn:aaid:aem:9913a059-4644-4e07-a049-7f72f2e28b5c/as/1731564-847__1.avif",
        "categories": [
          "Appliances",
          "Appliances > Refrigerators",
          "Appliances > Refrigerators > Top Freezer Refrigerators"
        ],
        "rating": 4.2566,
        "rating_count": 491
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/costco.searchResponseDoc

Field	Type	Required	Enum	Example	Description
code	integer	No		200
data	costco.SearchResponse	No
data.category	string	No
data.is_partial	boolean	No			IsPartial is true when a fallback source cannot reproduce the complete Costco search result set.
data.products	array	No
data.products[].brand	string	No
data.products[].categories	array	No
data.products[].id	string	No
data.products[].image_url	string	No
data.products[].model	string	No
data.products[].rating	number	No
data.products[].rating_count	integer	No
data.products[].title	string	No
data.products[].url	string	No
data.query	string	No
data.source	string	No	product_sitemap		Source is omitted for complete GDX search results. product_sitemap identifies a degraded query-only fallback whose ordering and count are based on product URL slugs rather than Costco's search index.
data.total_count	integer	No
msg	string	No		OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/costco/search?query=coffee" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

Costco search API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

Costco search API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related