Get Extract Status

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
  }
}

GET

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

x-api-key

string

required

Your API key for authentication

execution_id

string

required

The execution ID returned from POST /v2/extract

Query Parameters

page

number

default:"1"

Page number for paginated results (only applicable when status is “completed”)Minimum: 1

page_size

number

default:"50"

Number of results per page (only applicable when status is “completed”)Maximum: 100 Default: 50

Response

execution_id

string

The execution identifier

status

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

error

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”

data

array

Array of product results (only present when status is “completed” and results are available)

Hide Product Result

url

string

Original URL that was processed

success

boolean

Whether the product was successfully processed

product

object | null

Product data (null if processing failed)

Hide Product Object

title

string

Product title

description

string

Detailed product description

url

string

Product URL

brand

string | null

Product brand name

product_category

string | null

Full product category breadcrumb path

google_product_category_id

string | null

Google product category identifier

google_product_category_path

string | null

Full Google product category path

condition

string | null

Product condition (e.g. “new”, “used”, “refurbished”)

availability

string | null

Availability status string (e.g. “in_stock”, “out_of_stock”, “preorder”, “backorder”)

price

string | null

Product price as a value and currency string (e.g. “1628 USD”)

sale_price

string | null

Sale price as a value and currency string (e.g. “1365 USD”)

material

string | null

Product material description

gender

string | null

Target gender (e.g. “male”, “female”, “unisex”)

age_group

string | null

Target age group (e.g. “adult”, “kids”, “toddler”, “infant”, “newborn”)

size_system

string | null

Size system used (e.g. “US”, “UK”, “EU”)

dimensions_unit

string | null

Unit for dimension values (e.g. “in”, “cm”)

weight

string | null

Product weight value

height

string | null

Product height value

length

string | null

Product length value

width

string | null

Product width value

item_weight_unit

string | null

Unit for weight value (e.g. “lb”, “kg”)

images

array

Array of image objects.

Show Image object

url

string

Image URL

alt_text

string | null

Alt text

variants

array

Array of variant objects.

Show Variant object

variant_id

string

Variant ID

sku

string | null

SKU

shipping

string | null

Shipping information

is_eligible_search

string

Whether the product is eligible for search. “true” or “false”.

is_eligible_checkout

string

Whether the product is eligible for checkout. “true” or “false”.

review_count

number | null

Number of reviews

star_rating

number | null

Average star rating (e.g. 4.8)

rating_scale

number | null

Rating scale (e.g. 5)

reviews

array | null

Array of review objects.

Show Review object

date

string | null

Review date

title

string | null

Review title

rating

number | string | null

Rating

content

string | null

Review body

image_url

string | null

Review image URL

reviewer_name

string | null

Reviewer name

similar_products

array | null

Similar products when similar products discovery is enabled.

Show Similar product object

url

string

Product URL

brand

string | null

Brand name

title

string

Product title

similarity

string

“high” | “medium” | “low”

brand_pdp

object | null

Brand product detail page lookup result, identifying the original brand’s listing for this product.

Show Brand PDP object

brandName

string

Brand name

brandDomain

string

Brand website domain

brandPdpUrl

string

URL to the product on the brand’s own website

productTitle

string

Product title on the brand’s website

attributes

object | null

Product attributes when AI enrichment is enabled.

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.

platform

string | null

E-commerce platform (e.g. “shopify”)

platform_id

string | null

Platform-specific ID

is_digital

boolean | null

Whether the product is a digital/downloadable item

deep_research

object | null

In-depth product research organized by dimension (e.g. ergonomics, materials, competitive analysis). Structure varies by product category.

q_and_a

array | null

Array of Q&A objects.

Show Q&A object

question

string

Question

answer

string

Answer

confidence

string | null

Confidence level: “high”, “medium”, or “low”

meta

object

Response metadata

Show Meta Properties

progress

object | null

Real-time progress information (null if not available or when waiting for crawl)

Show Progress Properties

products_processed

number

Number of products successfully processed so far

products_total

number

Total number of products in the batch

percent_complete

number

Percentage of completion (0-100)

start_date

string | null

ISO 8601 timestamp when execution started (null if not started or waiting for crawl)

stop_date

string | null

ISO 8601 timestamp when execution completed or stopped (null if still running)

duration_ms

number | null

Total execution duration in milliseconds (null if not yet completed)

waiting_for

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)

result

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

products_requested

number

Total number of URLs submitted in the extraction request

products_successful

number

Number of URLs where product data was extracted successfully

products_failed

number

Number of URLs where extraction failed due to retriable issues. Equal to the sum of values in products_failed_by_reason.

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

automated_access_not_permitted

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.

other

number

URLs that encountered a temporary processing error (e.g. timeout, unexpected page state). Safe to retry immediately.

products_invalid

number

Number of URLs with input problems that cannot be resolved by retrying. Equal to the sum of values in products_invalid_by_reason.

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

non_product_url

number

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.

malformed_url

number

URLs with invalid format (e.g. missing protocol, unencoded characters). Fix the URL and resubmit.

products_pending

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"

{
  "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" with waiting_for in 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

List Extracts Cancel Extract

Get Started

API Reference

Guides

Resources

Migration Guides

Request

Query Parameters

Response

Polling Strategy

Get Started

API Reference

Guides

Resources

Migration Guides

Documentation Index

​Request

​Query Parameters

​Response

​Polling Strategy

Request

Query Parameters

Response

Polling Strategy