> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcatalog.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Extract Status
> Get extract status and results for an asynchronous extract job.
**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/extract`](/v2/api-reference/endpoints/extract/extract)
### Query 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 status
**Possible 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)
Original URL that was processed
Whether the product was successfully processed
Product data (null if processing failed)
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.
Image URL
Alt text
Array of variant objects.
Variant ID
SKU
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.
Review date
Review title
Rating
Review body
Review image URL
Reviewer name
Similar products when similar products discovery is enabled.
Product URL
Brand name
Product title
"high" | "medium" | "low"
Brand product detail page lookup result, identifying the original brand's listing for this product.
Brand name
Brand website domain
URL to the product on the brand's own website
Product title on the brand's website
Product attributes when AI enrichment is enabled.
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.
Question
Answer
Confidence level: "high", "medium", or "low"
Category of the question (e.g. "durability", "compatibility", "maintenance", "performance", "technical")
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)
Current page number
Number of results per page
Total number of results across all pages
Total number of pages
Whether there is a next page
Whether there is a previous page
Response metadata
Real-time progress information (null if not available or when waiting for crawl)
Number of products successfully processed so far
Total number of products in the batch
Percentage of completion (0-100)
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`.
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.
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.
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.
```powershell cURL theme={null}
# 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"
```
```javascript JavaScript theme={null}
// 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);
}
```
```python Python theme={null}
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'])
```
```json Status: Completed theme={null}
{
"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": "...",
"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
}
}
```
```json Status: Completed (Mixed Results) theme={null}
{
"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
}
}
```
```json Status: Running theme={null}
{
"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
}
}
}
```
```json Status: Failed (Execution Failed) theme={null}
{
"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:
1. **Initial Poll:** Check status immediately after receiving `execution_id`
2. **Handle Pending with Waiting For:** If status is `"pending"` with `waiting_for` in meta, the extraction is waiting for a crawl. Poll less frequently (every 30-60 seconds) until the crawl completes.
3. **Polling Interval:** Wait 5-10 seconds between polls for running executions
4. **Exponential Backoff:** Consider increasing wait time for long-running jobs
5. **Timeout:** Set a maximum wait time based on your batch size and whether you're waiting for a crawl