cURL
# Check execution status (urls input)
curl -X GET "https://api.getcatalog.ai/v2/extract/extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7" \
-H "x-api-key: $CATALOG_API_KEY"
# Get results with pagination
curl -X GET "https://api.getcatalog.ai/v2/extract/extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7?page=1&page_size=50" \
-H "x-api-key: $CATALOG_API_KEY"
{
"execution_id": "extract-urls-b45c2d8c-46b7-46c2-8fed-fa3788c75e2a",
"status": "completed",
"error": null,
"meta": {
"progress": {
"products_processed": 1,
"products_total": 1,
"percent_complete": 100
},
"start_date": "2026-01-28T22:30:05.823Z",
"stop_date": "2026-01-28T22:35:31.082Z",
"duration_ms": 325259,
"result": {
"products_requested": 1,
"products_successful": 1,
"products_failed": 0,
"products_failed_by_reason": {},
"products_invalid": 0,
"products_invalid_by_reason": {},
"products_pending": 0
},
"credits_used": 5
},
"data": [
{
"url": "https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111",
"product": {
"id": "6e6bd7bd-bfb5-4e05-85ee-4969628e741a",
"title": "Nike Air Force 1 '07",
"description": "Comfortable, durable and timeless—it's number one for a reason. ...",
"vendor": "nike.com",
"brand": "Nike",
"url": "https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111",
"handle": "cw2288-111",
"is_available": true,
"attributes": null,
"price": { "current_value": 115, "compare_at_value": 115, "currency": "USD" },
"images": [
{
"url": "https://static.nike.com/a/images/t_default/.../AIR+FORCE+1+%2707.png",
"alt_text": "Nike Air Force 1 '07 product image (primary)",
"position": 1,
"width": 400,
"height": 400,
"id": "img-1769639694151-0",
"variant_ids": ["variant-1769639694153-0", "_truncated"],
"attributes": null
},
{ "_truncated": "Additional image objects omitted for display" }
],
"options": [
{ "name": "Color", "position": 1, "values": ["White/White"] },
{ "name": "Size", "position": 2, "values": ["6", "6.5", "7", "_truncated", "18"] }
],
"variants": [
{
"id": "variant-1769639694153-0",
"title": "Nike Air Force 1 '07 - White/white - 6",
"is_available": true,
"price": { "current_value": 115, "compare_at_value": null, "currency": "USD" },
"sku": "CW2288-111",
"option1": "White/White",
"option2": "6",
"url": "https://www.nike.com/t/air-force-1-07-mens-shoes-jBrhbr/CW2288-111#size-6",
"image": {
"url": "https://static.nike.com/a/images/t_default/.../AIR+FORCE+1+%2707.png",
"alt_text": "Nike Air Force 1 '07 - White/White - 6 variant image",
"position": 1,
"width": 400,
"height": 400,
"id": "img-variant-variant-1769639694153-0",
"variant_ids": ["variant-1769639694153-0"]
}
},
{ "_truncated": "Additional variants omitted for display" }
],
"store_canonical_url": "https://www.nike.com/",
"store_domain": "www.nike.com",
"platform": null,
"platform_id": "CW2288-111",
"description_html": "<html>...</html>",
"product_type": null,
"google_product_category_id": null,
"google_product_category_path": null,
"tags": ["FOOTWEAR"],
"video_url": null,
"review_count": null,
"average_rating": null,
"rating_scale": null,
"faqs": null,
"reviews": null,
"updated_at": "2026-01-28T22:34:54.186Z",
"similar_products": null,
"affiliate_link": "https://wild.link/e?..."
},
"success": true,
"outcome": "success",
"retry": false,
"message": ""
}
],
"pagination": {
"page": 1,
"page_size": 50,
"total_items": 1,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
}
Extract
Get Extract Status
Get extract status and results for an asynchronous extract job.
GET
/
v2
/
extract
/
{execution_id}
cURL
# Check execution status (urls input)
curl -X GET "https://api.getcatalog.ai/v2/extract/extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7" \
-H "x-api-key: $CATALOG_API_KEY"
# Get results with pagination
curl -X GET "https://api.getcatalog.ai/v2/extract/extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7?page=1&page_size=50" \
-H "x-api-key: $CATALOG_API_KEY"
{
"execution_id": "extract-urls-b45c2d8c-46b7-46c2-8fed-fa3788c75e2a",
"status": "completed",
"error": null,
"meta": {
"progress": {
"products_processed": 1,
"products_total": 1,
"percent_complete": 100
},
"start_date": "2026-01-28T22:30:05.823Z",
"stop_date": "2026-01-28T22:35:31.082Z",
"duration_ms": 325259,
"result": {
"products_requested": 1,
"products_successful": 1,
"products_failed": 0,
"products_failed_by_reason": {},
"products_invalid": 0,
"products_invalid_by_reason": {},
"products_pending": 0
},
"credits_used": 5
},
"data": [
{
"url": "https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111",
"product": {
"id": "6e6bd7bd-bfb5-4e05-85ee-4969628e741a",
"title": "Nike Air Force 1 '07",
"description": "Comfortable, durable and timeless—it's number one for a reason. ...",
"vendor": "nike.com",
"brand": "Nike",
"url": "https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111",
"handle": "cw2288-111",
"is_available": true,
"attributes": null,
"price": { "current_value": 115, "compare_at_value": 115, "currency": "USD" },
"images": [
{
"url": "https://static.nike.com/a/images/t_default/.../AIR+FORCE+1+%2707.png",
"alt_text": "Nike Air Force 1 '07 product image (primary)",
"position": 1,
"width": 400,
"height": 400,
"id": "img-1769639694151-0",
"variant_ids": ["variant-1769639694153-0", "_truncated"],
"attributes": null
},
{ "_truncated": "Additional image objects omitted for display" }
],
"options": [
{ "name": "Color", "position": 1, "values": ["White/White"] },
{ "name": "Size", "position": 2, "values": ["6", "6.5", "7", "_truncated", "18"] }
],
"variants": [
{
"id": "variant-1769639694153-0",
"title": "Nike Air Force 1 '07 - White/white - 6",
"is_available": true,
"price": { "current_value": 115, "compare_at_value": null, "currency": "USD" },
"sku": "CW2288-111",
"option1": "White/White",
"option2": "6",
"url": "https://www.nike.com/t/air-force-1-07-mens-shoes-jBrhbr/CW2288-111#size-6",
"image": {
"url": "https://static.nike.com/a/images/t_default/.../AIR+FORCE+1+%2707.png",
"alt_text": "Nike Air Force 1 '07 - White/White - 6 variant image",
"position": 1,
"width": 400,
"height": 400,
"id": "img-variant-variant-1769639694153-0",
"variant_ids": ["variant-1769639694153-0"]
}
},
{ "_truncated": "Additional variants omitted for display" }
],
"store_canonical_url": "https://www.nike.com/",
"store_domain": "www.nike.com",
"platform": null,
"platform_id": "CW2288-111",
"description_html": "<html>...</html>",
"product_type": null,
"google_product_category_id": null,
"google_product_category_path": null,
"tags": ["FOOTWEAR"],
"video_url": null,
"review_count": null,
"average_rating": null,
"rating_scale": null,
"faqs": null,
"reviews": null,
"updated_at": "2026-01-28T22:34:54.186Z",
"similar_products": null,
"affiliate_link": "https://wild.link/e?..."
},
"success": true,
"outcome": "success",
"retry": false,
"message": ""
}
],
"pagination": {
"page": 1,
"page_size": 50,
"total_items": 1,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
}
When to use: After starting an extraction job with the POST endpoint, use this endpoint to:
- Check if processing is complete
- Monitor real-time progress
- Retrieve paginated results when processing completes
- Check if extraction is waiting for a crawl to complete
Request
Your API key for authentication
The execution ID returned from
POST /v2/extractQuery Parameters
Page number for paginated results (only applicable when status is “completed”)Minimum: 1
Number of results per page (only applicable when status is “completed”)Maximum: 100
Default: 50
Response
The execution identifier
Current execution statusPossible values:
"pending"- Execution has been created but not yet started (may be waiting for crawl)"running"- Execution is currently processing"completed"- Execution finished successfully"failed"- Execution failed or was aborted
Error message (always present, null if execution is successful or still running)Note: Error messages are sanitized for security. For vendor-based extractions waiting for a crawl, if the crawl fails, the error will be: “The crawl this extraction was waiting for failed or was canceled”
Array of product results (only present when status is “completed” and results are available)
Hide Product Result
Hide Product Result
Original URL that was processed
Whether the product was successfully processed
Product data (null if processing failed)
Hide Product Object
Hide Product Object
Product title
Detailed product description
Product URL
Product brand name
Full product category breadcrumb path
Google product category identifier
Full Google product category path
Product condition (e.g. “new”, “used”, “refurbished”)
Availability status string (e.g. “in_stock”, “out_of_stock”, “preorder”, “backorder”)
Product price as a value and currency string (e.g. “1628 USD”)
Sale price as a value and currency string (e.g. “1365 USD”)
Product material description
Target gender (e.g. “male”, “female”, “unisex”)
Target age group (e.g. “adult”, “kids”, “toddler”, “infant”, “newborn”)
Size system used (e.g. “US”, “UK”, “EU”)
Unit for dimension values (e.g. “in”, “cm”)
Product weight value
Product height value
Product length value
Product width value
Unit for weight value (e.g. “lb”, “kg”)
Array of image objects.
Array of variant objects.
Shipping information
Whether the product is eligible for search. “true” or “false”.
Whether the product is eligible for checkout. “true” or “false”.
Number of reviews
Average star rating (e.g. 4.8)
Rating scale (e.g. 5)
Array of review objects.
Show Review object
Show Review object
Similar products when similar products discovery is enabled.
Show Similar product object
Show Similar product object
Brand product detail page lookup result, identifying the original brand’s listing for this product.
Show Brand PDP object
Show Brand PDP object
Product attributes when AI enrichment is enabled.
Show Attributes object
Show Attributes object
Key-value object from AI enrichment. Structure is product-dependent; no fixed schema. May include semantic attributes (e.g. color, summary, features, material, placement, durability, care_instructions, additional_attributes) and other enriched fields.
E-commerce platform (e.g. “shopify”)
Platform-specific ID
Whether the product is a digital/downloadable item
In-depth product research organized by dimension (e.g. ergonomics, materials, competitive analysis). Structure varies by product category.
Array of Q&A objects.
The outcome category for this URL.Possible values:
"success"— Product data was extracted successfully"non_product_url"— The URL does not point to a product page (e.g. category page, 404, homepage redirect)"malformed_url"— The URL format is invalid or unparseable"automated_access_not_permitted"— The site’s bot protection blocked automated access"other"— A temporary error occurred during processing
Whether retrying this URL may produce a successful result. When
true, the failure is likely transient — resubmit the URL in a new request. When false, the URL itself needs fixing — check message for specifics.A human-readable description of the outcome with recommended next steps. Empty string on success.
The URL the browser landed on after following redirects. Only present when the final URL differs from the input
url. Useful for diagnosing non_product_url outcomes caused by redirects.Pagination information (only present when status is “completed” and results are available)
Response metadata
Show Meta Properties
Show Meta Properties
ISO 8601 timestamp when execution started (null if not started or waiting for crawl)
ISO 8601 timestamp when execution completed or stopped (null if still running)
Total execution duration in milliseconds (null if not yet completed)
Crawl execution ID that this extraction is waiting for (only present when status is “pending” and extraction is waiting for a crawl to complete)
Processing result statistics (only present when status is “completed” or “running”). The following invariant always holds:
products_successful + products_failed + products_invalid + products_pending = products_requested.Show Result Properties
Show Result Properties
Total number of URLs submitted in the extraction request
Number of URLs where product data was extracted successfully
Number of URLs where extraction failed due to retriable issues. Equal to the sum of values in
products_failed_by_reason.Breakdown of retriable failures by outcome. Keys are only present when their count is greater than zero. Resubmitting these URLs in a new extraction request may succeed.
Show Failed Breakdown
Show Failed Breakdown
URLs where the site’s bot protection blocked automated access. This is often transient — retrying typically succeeds. If it persists for a specific site, contact support.
URLs that encountered a temporary processing error (e.g. timeout, unexpected page state). Safe to retry immediately.
Number of URLs with input problems that cannot be resolved by retrying. Equal to the sum of values in
products_invalid_by_reason.Breakdown of invalid URLs by outcome. Keys are only present when their count is greater than zero. These URLs need to be corrected before resubmitting — retrying the same URL will produce the same result.
Show Invalid Breakdown
Show Invalid Breakdown
URLs that did not resolve to a product page. Common causes include category pages, 404s, and homepage redirects. Check the per-URL
final_url field to see where the browser ended up.URLs with invalid format (e.g. missing protocol, unencoded characters). Fix the URL and resubmit.
URLs still being processed. Always present;
0 when extraction is complete.cURL
# Check execution status (urls input)
curl -X GET "https://api.getcatalog.ai/v2/extract/extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7" \
-H "x-api-key: $CATALOG_API_KEY"
# Get results with pagination
curl -X GET "https://api.getcatalog.ai/v2/extract/extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7?page=1&page_size=50" \
-H "x-api-key: $CATALOG_API_KEY"
{
"execution_id": "extract-urls-b45c2d8c-46b7-46c2-8fed-fa3788c75e2a",
"status": "completed",
"error": null,
"meta": {
"progress": {
"products_processed": 1,
"products_total": 1,
"percent_complete": 100
},
"start_date": "2026-01-28T22:30:05.823Z",
"stop_date": "2026-01-28T22:35:31.082Z",
"duration_ms": 325259,
"result": {
"products_requested": 1,
"products_successful": 1,
"products_failed": 0,
"products_failed_by_reason": {},
"products_invalid": 0,
"products_invalid_by_reason": {},
"products_pending": 0
},
"credits_used": 5
},
"data": [
{
"url": "https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111",
"product": {
"id": "6e6bd7bd-bfb5-4e05-85ee-4969628e741a",
"title": "Nike Air Force 1 '07",
"description": "Comfortable, durable and timeless—it's number one for a reason. ...",
"vendor": "nike.com",
"brand": "Nike",
"url": "https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111",
"handle": "cw2288-111",
"is_available": true,
"attributes": null,
"price": { "current_value": 115, "compare_at_value": 115, "currency": "USD" },
"images": [
{
"url": "https://static.nike.com/a/images/t_default/.../AIR+FORCE+1+%2707.png",
"alt_text": "Nike Air Force 1 '07 product image (primary)",
"position": 1,
"width": 400,
"height": 400,
"id": "img-1769639694151-0",
"variant_ids": ["variant-1769639694153-0", "_truncated"],
"attributes": null
},
{ "_truncated": "Additional image objects omitted for display" }
],
"options": [
{ "name": "Color", "position": 1, "values": ["White/White"] },
{ "name": "Size", "position": 2, "values": ["6", "6.5", "7", "_truncated", "18"] }
],
"variants": [
{
"id": "variant-1769639694153-0",
"title": "Nike Air Force 1 '07 - White/white - 6",
"is_available": true,
"price": { "current_value": 115, "compare_at_value": null, "currency": "USD" },
"sku": "CW2288-111",
"option1": "White/White",
"option2": "6",
"url": "https://www.nike.com/t/air-force-1-07-mens-shoes-jBrhbr/CW2288-111#size-6",
"image": {
"url": "https://static.nike.com/a/images/t_default/.../AIR+FORCE+1+%2707.png",
"alt_text": "Nike Air Force 1 '07 - White/White - 6 variant image",
"position": 1,
"width": 400,
"height": 400,
"id": "img-variant-variant-1769639694153-0",
"variant_ids": ["variant-1769639694153-0"]
}
},
{ "_truncated": "Additional variants omitted for display" }
],
"store_canonical_url": "https://www.nike.com/",
"store_domain": "www.nike.com",
"platform": null,
"platform_id": "CW2288-111",
"description_html": "<html>...</html>",
"product_type": null,
"google_product_category_id": null,
"google_product_category_path": null,
"tags": ["FOOTWEAR"],
"video_url": null,
"review_count": null,
"average_rating": null,
"rating_scale": null,
"faqs": null,
"reviews": null,
"updated_at": "2026-01-28T22:34:54.186Z",
"similar_products": null,
"affiliate_link": "https://wild.link/e?..."
},
"success": true,
"outcome": "success",
"retry": false,
"message": ""
}
],
"pagination": {
"page": 1,
"page_size": 50,
"total_items": 1,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
}
Polling Strategy
For best results when waiting for completion:- Initial Poll: Check status immediately after receiving
execution_id - Handle Pending with Waiting For: If status is
"pending"withwaiting_forin meta, the extraction is waiting for a crawl. Poll less frequently (every 30-60 seconds) until the crawl completes. - Polling Interval: Wait 5-10 seconds between polls for running executions
- Exponential Backoff: Consider increasing wait time for long-running jobs
- Timeout: Set a maximum wait time based on your batch size and whether you’re waiting for a crawl
⌘I