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"
// Check execution status
const executionId = 'extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7';
const response = await fetch(
`https://api.getcatalog.ai/v2/extract/${executionId}?page=1&page_size=50`,
{
headers: {
'x-api-key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();
if (data.status === 'completed') {
const result = data.meta.result;
console.log(`Successful: ${result.products_successful}, Failed: ${result.products_failed}, Invalid: ${result.products_invalid}`);
const retriableUrls = data.data
.filter(item => item.retry)
.map(item => item.url);
if (retriableUrls.length > 0) {
console.log('Retriable URLs:', retriableUrls);
}
data.data
.filter(item => !item.success && !item.retry)
.forEach(item => console.warn(`${item.outcome}: ${item.url} — ${item.message}`));
} else if (data.status === 'running') {
const progress = data.meta.progress;
console.log(`Progress: ${progress.percent_complete}% (${progress.products_processed}/${progress.products_total})`);
console.log(`Started: ${data.meta.start_date}`);
} else if (data.status === 'pending') {
if (data.meta.waiting_for) {
console.log(`Waiting for crawl to complete: ${data.meta.waiting_for}`);
} else {
console.log('Execution is pending');
}
} else if (data.status === 'failed') {
console.error('Error:', data.error);
}
import requests
execution_id = 'extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7'
# Check execution status
response = requests.get(
f'https://api.getcatalog.ai/v2/extract/{execution_id}',
headers={'x-api-key': 'YOUR_API_KEY'},
params={'page': 1, 'page_size': 50},
)
data = response.json()
if data['status'] == 'completed':
result = data['meta']['result']
print(f"Successful: {result['products_successful']}, Failed: {result['products_failed']}, Invalid: {result['products_invalid']}")
retriable = [item for item in data['data'] if item.get('retry')]
if retriable:
print('Retriable URLs:', [item['url'] for item in retriable])
for item in data['data']:
if not item['success'] and not item.get('retry'):
print(f"{item['outcome']}: {item['url']} — {item['message']}")
elif data['status'] == 'running':
progress = data['meta']['progress']
print(
f"Progress: {progress['percent_complete']}% "
f"({progress['products_processed']}/{progress['products_total']})"
)
print(f"Started: {data['meta']['start_date']}")
elif data['status'] == 'pending':
if data['meta'].get('waiting_for'):
print(f"Waiting for crawl to complete: {data['meta']['waiting_for']}")
else:
print('Execution is pending')
elif data['status'] == 'failed':
print('Error:', data['error'])
{
"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
}
}
{
"execution_id": "extract-urls-a12b3c4d-5678-9012-abcd-ef3456789012",
"status": "completed",
"error": null,
"meta": {
"progress": {
"products_processed": 3,
"products_total": 3,
"percent_complete": 100
},
"start_date": "2026-03-20T10:00:00.000Z",
"stop_date": "2026-03-20T10:05:00.000Z",
"duration_ms": 300000,
"result": {
"products_requested": 3,
"products_successful": 1,
"products_failed": 1,
"products_failed_by_reason": {
"automated_access_not_permitted": 1
},
"products_invalid": 1,
"products_invalid_by_reason": {
"non_product_url": 1
},
"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",
"_truncated": "Full product object omitted for display"
},
"success": true,
"outcome": "success",
"retry": false,
"message": ""
},
{
"url": "https://www.example.com/products/limited-edition",
"product": null,
"success": false,
"outcome": "non_product_url",
"retry": false,
"message": "This URL does not point to a product page.",
"final_url": "https://www.example.com/collections/all"
},
{
"url": "https://protected-store.com/products/item-42",
"product": null,
"success": false,
"outcome": "automated_access_not_permitted",
"retry": true,
"message": "The site could not be reached. Please retry this URL."
}
],
"pagination": {
"page": 1,
"page_size": 50,
"total_items": 3,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
}
{
"execution_id": "extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7",
"status": "running",
"error": null,
"meta": {
"progress": {
"products_processed": 45,
"products_total": 100,
"percent_complete": 45
},
"start_date": "2025-01-15T10:30:00.000Z",
"stop_date": null,
"duration_ms": 125000,
"result": {
"products_requested": 100,
"products_successful": 40,
"products_failed": 3,
"products_failed_by_reason": {
"automated_access_not_permitted": 2,
"other": 1
},
"products_invalid": 2,
"products_invalid_by_reason": {
"non_product_url": 1,
"malformed_url": 1
},
"products_pending": 55
}
}
}
{
"execution_id": "extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7",
"status": "failed",
"error": "The operation failed. Please retry or contact support with this execution ID.",
"meta": {
"progress": {
"products_processed": 12,
"products_total": 100,
"percent_complete": 12
},
"start_date": "2025-01-15T10:30:00.000Z",
"stop_date": "2025-01-15T10:31:15.000Z",
"duration_ms": 75000,
"result": {
"products_requested": 100,
"products_successful": 8,
"products_failed": 3,
"products_failed_by_reason": {
"automated_access_not_permitted": 2,
"other": 1
},
"products_invalid": 1,
"products_invalid_by_reason": {
"non_product_url": 1
},
"products_pending": 88
}
}
}
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"
// Check execution status
const executionId = 'extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7';
const response = await fetch(
`https://api.getcatalog.ai/v2/extract/${executionId}?page=1&page_size=50`,
{
headers: {
'x-api-key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();
if (data.status === 'completed') {
const result = data.meta.result;
console.log(`Successful: ${result.products_successful}, Failed: ${result.products_failed}, Invalid: ${result.products_invalid}`);
const retriableUrls = data.data
.filter(item => item.retry)
.map(item => item.url);
if (retriableUrls.length > 0) {
console.log('Retriable URLs:', retriableUrls);
}
data.data
.filter(item => !item.success && !item.retry)
.forEach(item => console.warn(`${item.outcome}: ${item.url} — ${item.message}`));
} else if (data.status === 'running') {
const progress = data.meta.progress;
console.log(`Progress: ${progress.percent_complete}% (${progress.products_processed}/${progress.products_total})`);
console.log(`Started: ${data.meta.start_date}`);
} else if (data.status === 'pending') {
if (data.meta.waiting_for) {
console.log(`Waiting for crawl to complete: ${data.meta.waiting_for}`);
} else {
console.log('Execution is pending');
}
} else if (data.status === 'failed') {
console.error('Error:', data.error);
}
import requests
execution_id = 'extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7'
# Check execution status
response = requests.get(
f'https://api.getcatalog.ai/v2/extract/{execution_id}',
headers={'x-api-key': 'YOUR_API_KEY'},
params={'page': 1, 'page_size': 50},
)
data = response.json()
if data['status'] == 'completed':
result = data['meta']['result']
print(f"Successful: {result['products_successful']}, Failed: {result['products_failed']}, Invalid: {result['products_invalid']}")
retriable = [item for item in data['data'] if item.get('retry')]
if retriable:
print('Retriable URLs:', [item['url'] for item in retriable])
for item in data['data']:
if not item['success'] and not item.get('retry'):
print(f"{item['outcome']}: {item['url']} — {item['message']}")
elif data['status'] == 'running':
progress = data['meta']['progress']
print(
f"Progress: {progress['percent_complete']}% "
f"({progress['products_processed']}/{progress['products_total']})"
)
print(f"Started: {data['meta']['start_date']}")
elif data['status'] == 'pending':
if data['meta'].get('waiting_for'):
print(f"Waiting for crawl to complete: {data['meta']['waiting_for']}")
else:
print('Execution is pending')
elif data['status'] == 'failed':
print('Error:', data['error'])
{
"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
}
}
{
"execution_id": "extract-urls-a12b3c4d-5678-9012-abcd-ef3456789012",
"status": "completed",
"error": null,
"meta": {
"progress": {
"products_processed": 3,
"products_total": 3,
"percent_complete": 100
},
"start_date": "2026-03-20T10:00:00.000Z",
"stop_date": "2026-03-20T10:05:00.000Z",
"duration_ms": 300000,
"result": {
"products_requested": 3,
"products_successful": 1,
"products_failed": 1,
"products_failed_by_reason": {
"automated_access_not_permitted": 1
},
"products_invalid": 1,
"products_invalid_by_reason": {
"non_product_url": 1
},
"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",
"_truncated": "Full product object omitted for display"
},
"success": true,
"outcome": "success",
"retry": false,
"message": ""
},
{
"url": "https://www.example.com/products/limited-edition",
"product": null,
"success": false,
"outcome": "non_product_url",
"retry": false,
"message": "This URL does not point to a product page.",
"final_url": "https://www.example.com/collections/all"
},
{
"url": "https://protected-store.com/products/item-42",
"product": null,
"success": false,
"outcome": "automated_access_not_permitted",
"retry": true,
"message": "The site could not be reached. Please retry this URL."
}
],
"pagination": {
"page": 1,
"page_size": 50,
"total_items": 3,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
}
{
"execution_id": "extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7",
"status": "running",
"error": null,
"meta": {
"progress": {
"products_processed": 45,
"products_total": 100,
"percent_complete": 45
},
"start_date": "2025-01-15T10:30:00.000Z",
"stop_date": null,
"duration_ms": 125000,
"result": {
"products_requested": 100,
"products_successful": 40,
"products_failed": 3,
"products_failed_by_reason": {
"automated_access_not_permitted": 2,
"other": 1
},
"products_invalid": 2,
"products_invalid_by_reason": {
"non_product_url": 1,
"malformed_url": 1
},
"products_pending": 55
}
}
}
{
"execution_id": "extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7",
"status": "failed",
"error": "The operation failed. Please retry or contact support with this execution ID.",
"meta": {
"progress": {
"products_processed": 12,
"products_total": 100,
"percent_complete": 12
},
"start_date": "2025-01-15T10:30:00.000Z",
"stop_date": "2025-01-15T10:31:15.000Z",
"duration_ms": 75000,
"result": {
"products_requested": 100,
"products_successful": 8,
"products_failed": 3,
"products_failed_by_reason": {
"automated_access_not_permitted": 2,
"other": 1
},
"products_invalid": 1,
"products_invalid_by_reason": {
"non_product_url": 1
},
"products_pending": 88
}
}
}
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
string
required
Your API key for authentication
string
required
The execution ID returned from
POST /v2/extractQuery Parameters
number
default:"1"
Page number for paginated results (only applicable when status is “completed”)Minimum: 1
number
default:"50"
Number of results per page (only applicable when status is “completed”)Maximum: 100
Default: 50
Response
string
The execution identifier
string
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
string | null
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
Array of product results (only present when status is “completed” and results are available)
Hide Product Result
Hide Product Result
string
Original URL that was processed
boolean
Whether the product was successfully processed
object | null
Product data (null if processing failed)
Hide Product Object
Hide Product Object
string
Product title
string
Detailed product description
string
Product URL
string | null
Product brand name
string | null
Full product category breadcrumb path
string | null
Google product category identifier
string | null
Full Google product category path
string | null
Product condition (e.g. “new”, “used”, “refurbished”)
string | null
Availability status string (e.g. “in_stock”, “out_of_stock”, “preorder”, “backorder”)
string | null
Product price as a value and currency string (e.g. “1628 USD”)
string | null
Sale price as a value and currency string (e.g. “1365 USD”)
string | null
Product material description
string | null
Target gender (e.g. “male”, “female”, “unisex”)
string | null
Target age group (e.g. “adult”, “kids”, “toddler”, “infant”, “newborn”)
string | null
Size system used (e.g. “US”, “UK”, “EU”)
string | null
Unit for dimension values (e.g. “in”, “cm”)
string | null
Product weight value
string | null
Product height value
string | null
Product length value
string | null
Product width value
string | null
Unit for weight value (e.g. “lb”, “kg”)
array
Array of image objects.
array
Array of variant objects.
string | null
Shipping information
string
Whether the product is eligible for search. “true” or “false”.
string
Whether the product is eligible for checkout. “true” or “false”.
number | null
Number of reviews
number | null
Average star rating (e.g. 4.8)
number | null
Rating scale (e.g. 5)
array | null
Array of review objects.
Show Review object
Show Review object
array | null
Similar products when similar products discovery is enabled.
Show Similar product object
Show Similar product object
object | null
Brand product detail page lookup result, identifying the original brand’s listing for this product.
Show Brand PDP object
Show Brand PDP object
object | null
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.
string | null
E-commerce platform (e.g. “shopify”)
string | null
Platform-specific ID
boolean | null
Whether the product is a digital/downloadable item
object | null
In-depth product research organized by dimension (e.g. ergonomics, materials, competitive analysis). Structure varies by product category.
array | null
Array of Q&A objects.
string
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
boolean
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.string
A human-readable description of the outcome with recommended next steps. Empty string on success.
string
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.object
Pagination information (only present when status is “completed” and results are available)
object
Response metadata
Show Meta Properties
Show Meta Properties
object | null
string | null
ISO 8601 timestamp when execution started (null if not started or waiting for crawl)
string | null
ISO 8601 timestamp when execution completed or stopped (null if still running)
number | null
Total execution duration in milliseconds (null if not yet completed)
string
Crawl execution ID that this extraction is waiting for (only present when status is “pending” and extraction is waiting for a crawl to complete)
object
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
number
Total number of URLs submitted in the extraction request
number
Number of URLs where product data was extracted successfully
number
Number of URLs where extraction failed due to retriable issues. Equal to the sum of values in
products_failed_by_reason.object
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
number
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.
number
URLs that encountered a temporary processing error (e.g. timeout, unexpected page state). Safe to retry immediately.
number
Number of URLs with input problems that cannot be resolved by retrying. Equal to the sum of values in
products_invalid_by_reason.object
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
number
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"
// Check execution status
const executionId = 'extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7';
const response = await fetch(
`https://api.getcatalog.ai/v2/extract/${executionId}?page=1&page_size=50`,
{
headers: {
'x-api-key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();
if (data.status === 'completed') {
const result = data.meta.result;
console.log(`Successful: ${result.products_successful}, Failed: ${result.products_failed}, Invalid: ${result.products_invalid}`);
const retriableUrls = data.data
.filter(item => item.retry)
.map(item => item.url);
if (retriableUrls.length > 0) {
console.log('Retriable URLs:', retriableUrls);
}
data.data
.filter(item => !item.success && !item.retry)
.forEach(item => console.warn(`${item.outcome}: ${item.url} — ${item.message}`));
} else if (data.status === 'running') {
const progress = data.meta.progress;
console.log(`Progress: ${progress.percent_complete}% (${progress.products_processed}/${progress.products_total})`);
console.log(`Started: ${data.meta.start_date}`);
} else if (data.status === 'pending') {
if (data.meta.waiting_for) {
console.log(`Waiting for crawl to complete: ${data.meta.waiting_for}`);
} else {
console.log('Execution is pending');
}
} else if (data.status === 'failed') {
console.error('Error:', data.error);
}
import requests
execution_id = 'extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7'
# Check execution status
response = requests.get(
f'https://api.getcatalog.ai/v2/extract/{execution_id}',
headers={'x-api-key': 'YOUR_API_KEY'},
params={'page': 1, 'page_size': 50},
)
data = response.json()
if data['status'] == 'completed':
result = data['meta']['result']
print(f"Successful: {result['products_successful']}, Failed: {result['products_failed']}, Invalid: {result['products_invalid']}")
retriable = [item for item in data['data'] if item.get('retry')]
if retriable:
print('Retriable URLs:', [item['url'] for item in retriable])
for item in data['data']:
if not item['success'] and not item.get('retry'):
print(f"{item['outcome']}: {item['url']} — {item['message']}")
elif data['status'] == 'running':
progress = data['meta']['progress']
print(
f"Progress: {progress['percent_complete']}% "
f"({progress['products_processed']}/{progress['products_total']})"
)
print(f"Started: {data['meta']['start_date']}")
elif data['status'] == 'pending':
if data['meta'].get('waiting_for'):
print(f"Waiting for crawl to complete: {data['meta']['waiting_for']}")
else:
print('Execution is pending')
elif data['status'] == 'failed':
print('Error:', data['error'])
{
"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
}
}
{
"execution_id": "extract-urls-a12b3c4d-5678-9012-abcd-ef3456789012",
"status": "completed",
"error": null,
"meta": {
"progress": {
"products_processed": 3,
"products_total": 3,
"percent_complete": 100
},
"start_date": "2026-03-20T10:00:00.000Z",
"stop_date": "2026-03-20T10:05:00.000Z",
"duration_ms": 300000,
"result": {
"products_requested": 3,
"products_successful": 1,
"products_failed": 1,
"products_failed_by_reason": {
"automated_access_not_permitted": 1
},
"products_invalid": 1,
"products_invalid_by_reason": {
"non_product_url": 1
},
"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",
"_truncated": "Full product object omitted for display"
},
"success": true,
"outcome": "success",
"retry": false,
"message": ""
},
{
"url": "https://www.example.com/products/limited-edition",
"product": null,
"success": false,
"outcome": "non_product_url",
"retry": false,
"message": "This URL does not point to a product page.",
"final_url": "https://www.example.com/collections/all"
},
{
"url": "https://protected-store.com/products/item-42",
"product": null,
"success": false,
"outcome": "automated_access_not_permitted",
"retry": true,
"message": "The site could not be reached. Please retry this URL."
}
],
"pagination": {
"page": 1,
"page_size": 50,
"total_items": 3,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
}
{
"execution_id": "extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7",
"status": "running",
"error": null,
"meta": {
"progress": {
"products_processed": 45,
"products_total": 100,
"percent_complete": 45
},
"start_date": "2025-01-15T10:30:00.000Z",
"stop_date": null,
"duration_ms": 125000,
"result": {
"products_requested": 100,
"products_successful": 40,
"products_failed": 3,
"products_failed_by_reason": {
"automated_access_not_permitted": 2,
"other": 1
},
"products_invalid": 2,
"products_invalid_by_reason": {
"non_product_url": 1,
"malformed_url": 1
},
"products_pending": 55
}
}
}
{
"execution_id": "extract-urls-965b1912-6af0-4ed8-b7e3-184b85e788b7",
"status": "failed",
"error": "The operation failed. Please retry or contact support with this execution ID.",
"meta": {
"progress": {
"products_processed": 12,
"products_total": 100,
"percent_complete": 12
},
"start_date": "2025-01-15T10:30:00.000Z",
"stop_date": "2025-01-15T10:31:15.000Z",
"duration_ms": 75000,
"result": {
"products_requested": 100,
"products_successful": 8,
"products_failed": 3,
"products_failed_by_reason": {
"automated_access_not_permitted": 2,
"other": 1
},
"products_invalid": 1,
"products_invalid_by_reason": {
"non_product_url": 1
},
"products_pending": 88
}
}
}
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