> ## 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 Execution Status

> Get extract status and results for an asynchronous extract job.

<Tip>
  **When to use:** After starting a batch processing job with the POST endpoint, use this endpoint to:

  * Check if processing is complete
  * Monitor real-time progress
  * Retrieve paginated results when processing completes
</Tip>

<Tip>
  **Managing Executions:**

  * **View All Executions:** Use [`GET /v1/products`](/v1/api-reference/endpoints/extract/list-products-executions) to see all your processing jobs
  * **Cancel Running Executions:** If you need to stop a running execution, use [`DELETE /v1/products/{execution_id}`](/v1/api-reference/endpoints/extract/cancel-products-execution)
</Tip>

<Note>
  **Authentication Required:** This endpoint requires a valid API key. The API key is verified, but execution IDs are not restricted to specific API keys. Keep your execution IDs secure.
</Note>

## Request

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

<ParamField path="execution_id" type="string" required>
  The execution ID returned from [`POST /v1/products`](/v1/api-reference/endpoints/extract/retrieve-products)

  **Format:** `products-batch-{uuid}`

  **Note:** If the execution ID does not exist, the endpoint returns a 404 Not Found error.
</ParamField>

### Query Parameters

<ParamField query="page" type="number" default="1">
  Page number for paginated results (only applicable when status is "completed")

  **Minimum:** 1
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of results per page (only applicable when status is "completed")

  **Maximum:** 100
</ParamField>

## Response

<ResponseField name="status" type="string">
  Current execution status

  **Possible values:**

  * `"pending"` - Execution has been created but not yet started
  * `"running"` - Execution is currently processing
  * `"completed"` - Execution finished successfully
  * `"failed"` - Execution failed or was aborted
</ResponseField>

<ResponseField name="progress" type="object | null">
  Real-time progress information (null if not available)

  <Expandable title="Progress Properties">
    <ResponseField name="products_processed" type="number">
      Number of products successfully processed so far
    </ResponseField>

    <ResponseField name="urls_completed" type="number">
      Number of URLs that have been completed (successfully or with errors)
    </ResponseField>

    <ResponseField name="total_urls" type="number">
      Total number of URLs in the batch
    </ResponseField>

    <ResponseField name="percent_complete" type="number">
      Percentage of completion (0-100)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message (always present, null if execution is successful or still running)
</ResponseField>

<ResponseField name="results" type="object" optional>
  Product results (only present when status is "completed")

  <Expandable title="Results Properties" defaultOpen>
    <ResponseField name="products" type="array">
      Array of product results, one for each input URL

      <Expandable title="Product Result" defaultOpen>
        <ResponseField name="url" type="string">
          Original URL that was processed
        </ResponseField>

        <ResponseField name="success" type="boolean">
          Whether the product was successfully processed
        </ResponseField>

        <ResponseField name="product" type="object | null">
          Product data (null if processing failed)

          <Expandable title="Product Properties" defaultOpen>
            <ResponseField name="id" type="string">
              Unique product identifier
            </ResponseField>

            <ResponseField name="title" type="string">
              Product title
            </ResponseField>

            <ResponseField name="description" type="string">
              Detailed product description
            </ResponseField>

            <ResponseField name="vendor" type="string">
              Store/retailer name (e.g., "net-a-porter", "Nike")
            </ResponseField>

            <ResponseField name="brand" type="string | null">
              Product brand name (e.g., "LOEFFLER RANDALL", "Nike")
            </ResponseField>

            <ResponseField name="url" type="string">
              Product URL
            </ResponseField>

            <ResponseField name="handle" type="string">
              Product handle/slug
            </ResponseField>

            <ResponseField name="is_available" type="boolean">
              Product availability status
            </ResponseField>

            <ResponseField name="price_amount" type="number | null">
              Price in dollars
            </ResponseField>

            <ResponseField name="price_currency" type="string | null">
              Currency code (e.g., "USD")
            </ResponseField>

            <ResponseField name="min_price" type="number | null">
              Minimum price for variants
            </ResponseField>

            <ResponseField name="max_price" type="number | null">
              Maximum price for variants
            </ResponseField>

            <ResponseField name="images" type="array">
              Array of product images
            </ResponseField>

            <ResponseField name="options" type="array">
              Array of product options (size, color, etc.)
            </ResponseField>

            <ResponseField name="variants" type="array">
              Array of product variants with detailed information
            </ResponseField>

            <ResponseField name="store_canonical_url" type="string | null">
              Canonical store URL
            </ResponseField>

            <ResponseField name="store_domain" type="string">
              Store domain
            </ResponseField>

            <ResponseField name="platform" type="string | null">
              E-commerce platform (null if not identified)
            </ResponseField>

            <ResponseField name="platform_id" type="string | null">
              Platform-specific ID
            </ResponseField>

            <ResponseField name="description_html" type="string | null">
              HTML-formatted description
            </ResponseField>

            <ResponseField name="product_type" type="string | null">
              Product type/category
            </ResponseField>

            <ResponseField name="google_product_category_id" type="string | null">
              Google product category identifier
            </ResponseField>

            <ResponseField name="google_product_category_path" type="string | null">
              Full Google product category path
            </ResponseField>

            <ResponseField name="tags" type="array">
              Array of product tags/categories
            </ResponseField>

            <ResponseField name="video_url" type="string | null">
              Product video URL (if available)
            </ResponseField>

            <ResponseField name="updated_at" type="string">
              Last update timestamp (ISO 8601)
            </ResponseField>

            <ResponseField name="attributes" type="object">
              Comprehensive product attributes (when AI enrichment is enabled)
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="outcome" type="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
        </ResponseField>

        <ResponseField name="retry" type="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.
        </ResponseField>

        <ResponseField name="message" type="string">
          A human-readable description of the outcome with recommended next steps. Empty string on success.
        </ResponseField>

        <ResponseField name="final_url" type="string" optional>
          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.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="meta" type="object">
      Processing metadata and summary statistics. The following invariant always holds: `total_successful + total_failed + total_invalid + total_pending = total_requested`.

      <Expandable title="Meta Properties">
        <ResponseField name="total_requested" type="number">
          Total number of URLs submitted in the extraction request
        </ResponseField>

        <ResponseField name="total_successful" type="number">
          Number of URLs where product data was extracted successfully
        </ResponseField>

        <ResponseField name="total_failed" type="number">
          Number of URLs where extraction failed due to retriable issues. Equal to the sum of values in `total_failed_by_reason`.
        </ResponseField>

        <ResponseField name="total_failed_by_reason" type="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.

          <Expandable title="Failed Breakdown">
            <ResponseField name="automated_access_not_permitted" type="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.
            </ResponseField>

            <ResponseField name="other" type="number">
              URLs that encountered a temporary processing error (e.g. timeout, unexpected page state). Safe to retry immediately.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="total_invalid" type="number">
          Number of URLs with input problems that cannot be resolved by retrying. Equal to the sum of values in `total_invalid_by_reason`.
        </ResponseField>

        <ResponseField name="total_invalid_by_reason" type="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.

          <Expandable title="Invalid Breakdown">
            <ResponseField name="non_product_url" type="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.
            </ResponseField>

            <ResponseField name="malformed_url" type="number">
              URLs with invalid format (e.g. missing protocol, unencoded characters). Fix the URL and resubmit.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="total_pending" type="number">
          URLs still being processed. Always present; `0` when extraction is complete.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" optional>
  Pagination information (only present when status is "completed" and results are available)

  <Expandable title="Pagination Properties">
    <ResponseField name="page" type="number">
      Current page number
    </ResponseField>

    <ResponseField name="limit" type="number">
      Number of results per page
    </ResponseField>

    <ResponseField name="total_items" type="number">
      Total number of results across all pages
    </ResponseField>

    <ResponseField name="total_pages" type="number">
      Total number of pages
    </ResponseField>

    <ResponseField name="has_next" type="boolean">
      Whether there is a next page
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample dropdown>
  ```powershell cURL theme={null}
  # Check execution status
  curl -X GET "https://api.getcatalog.ai/v1/products/products-batch-550e8400-e29b-41d4-a716-446655440000" \
    -H "x-api-key: $CATALOG_API_KEY"

  # Get results with pagination
  curl -X GET "https://api.getcatalog.ai/v1/products/products-batch-550e8400-e29b-41d4-a716-446655440000?page=1&limit=50" \
    -H "x-api-key: $CATALOG_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  // Check execution status
  const executionId = 'products-batch-550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://api.getcatalog.ai/v1/products/${executionId}?page=1&limit=50`,
    {
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  if (data.status === 'completed') {
    const meta = data.results.meta;
    console.log(`Successful: ${meta.total_successful}, Failed: ${meta.total_failed}, Invalid: ${meta.total_invalid}`);

    const retriableUrls = data.results.products
      .filter(item => item.retry)
      .map(item => item.url);
    if (retriableUrls.length > 0) {
      console.log('Retriable URLs:', retriableUrls);
    }

    data.results.products
      .filter(item => !item.success && !item.retry)
      .forEach(item => console.warn(`${item.outcome}: ${item.url} — ${item.message}`));
  } else if (data.status === 'running') {
    console.log(`Progress: ${data.progress.percent_complete}%`);
  } else if (data.status === 'failed') {
    console.error('Error:', data.error);
  }
  ```

  ```python Python theme={null}
  import requests
  import time

  execution_id = 'products-batch-550e8400-e29b-41d4-a716-446655440000'

  # Poll for completion
  while True:
      response = requests.get(
          f'https://api.getcatalog.ai/v1/products/{execution_id}',
          headers={'x-api-key': 'YOUR_API_KEY'},
          params={'page': 1, 'limit': 50}
      )
      
      data = response.json()
      
      if data['status'] == 'completed':
          meta = data['results']['meta']
          print(f"Successful: {meta['total_successful']}, Failed: {meta['total_failed']}, Invalid: {meta['total_invalid']}")

          retriable = [item for item in data['results']['products'] if item.get('retry')]
          if retriable:
              print('Retriable URLs:', [item['url'] for item in retriable])

          for item in data['results']['products']:
              if not item['success'] and not item.get('retry'):
                  print(f"{item['outcome']}: {item['url']} — {item['message']}")
          break
      elif data['status'] == 'running':
          progress = data.get('progress', {})
          print(f"Progress: {progress.get('percent_complete', 0)}%")
          time.sleep(5)  # Wait 5 seconds before next poll
      elif data['status'] == 'failed':
          print('Error:', data.get('error'))
          break
  ```
</RequestExample>

<ResponseExample>
  ```json Status: Completed theme={null}
  {
    "status": "completed",
    "progress": {
      "products_processed": 1,
      "urls_completed": 1,
      "total_urls": 1,
      "percent_complete": 100
    },
    "error": null,
    "credits_used": 5,
    "results": {
      "products": [
        {
          "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. ... Style: CW2288-111",
            "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": {
              "additional_attributes": [
                "classic '80s construction",
                "bold design details",
                "smooth leather upper",
                "... more ..."
              ],
              "age_group": "adult",
              "gender": "unisex",
              "summary": "Timeless Nike Air Force 1 '07 sneakers combining classic '80s construction with smooth leather and durable, comfortable design.",
              "features": "Durable construction, cushioned midsole for support, and iconic silhouette suitable for various occasions.",
              "care_instructions": "Wipe clean with a damp cloth, avoid heavy cleaning solutions, air dry away from direct heat.",
              "color": { "iscc_family": "white", "merchant_label": "White/White" },
              "material": { "primary": "leather", "merchant_label": "Smooth Leather" },
              "pattern": "solid",
              "closure_type": "lace-up",
              "season": ["year-round"],
              "style": ["casual", "classic", "streetwear"],
              "mood": ["confident", "timeless"],
              "occasion": ["everyday", "casual", "sports-event"],
              "additional_product_information": "Benefits: ...\nProduct details: ...\nFit note: Fits large; we recommend ordering a half size down."
            },
            "price": { "currency": "USD", "current_value": 115, "compare_at_value": 115 },
            "images": [
              {
                "id": "img-1769639694151-0",
                "url": "https://static.nike.com/a/images/t_default/.../AIR+FORCE+1+%2707.png",
                "width": 400,
                "height": 400,
                "alt_text": "Nike Air Force 1 '07 product image (primary)",
                "position": 1,
                "variant_ids": ["variant-1769639694153-0", "..."],
                "attributes": null
              },
              "..."
            ],
            "options": [
              { "name": "Color", "values": ["White/White"], "position": 1 },
              { "name": "Size", "values": ["6", "6.5", "7", "...", "18"], "position": 2 }
            ],
            "variants": [
              {
                "id": "variant-1769639694153-0",
                "sku": "CW2288-111",
                "url": "https://www.nike.com/t/air-force-1-07-mens-shoes-jBrhbr/CW2288-111#size-6",
                "image": {
                  "id": "img-variant-variant-1769639694153-0",
                  "url": "https://static.nike.com/a/images/t_default/.../AIR+FORCE+1+%2707.png",
                  "width": 400,
                  "height": 400,
                  "alt_text": "Nike Air Force 1 '07 - White/White - 6 variant image",
                  "position": 1,
                  "variant_ids": ["variant-1769639694153-0"]
                },
                "price": { "currency": "USD", "current_value": 115, "compare_at_value": null },
                "title": "Nike Air Force 1 '07 - White/white - 6",
                "option1": "White/White",
                "option2": "6",
                "is_available": true,
                "affiliate_link": "https://wild.link/e?...#size-6"
              },
              "..."
            ],
            "store_canonical_url": "https://www.nike.com/",
            "store_domain": "www.nike.com",
            "platform": null,
            "platform_id": "CW2288-111",
            "description_html": "<html>...</html>",
            "product_type": "FOOTWEAR",
            "google_product_category_id": "187",
            "google_product_category_path": "Apparel & Accessories > Shoes",
            "tags": ["FOOTWEAR"],
            "video_url": null,
            "review_count": null,
            "average_rating": null,
            "rating_scale": null,
            "faqs": null,
            "reviews": null,
            "updated_at": "2026-01-28T22:53:52.255Z",
            "similar_products": null,
            "affiliate_link": "https://wild.link/e?...CW2288-111"
          },
          "success": true,
          "outcome": "success",
          "retry": false,
          "message": ""
        }
      ],
      "meta": {
        "total_requested": 1,
        "total_successful": 1,
        "total_failed": 0,
        "total_failed_by_reason": {},
        "total_invalid": 0,
        "total_invalid_by_reason": {},
        "total_pending": 0
      }
    },
    "pagination": {
      "page": 1,
      "limit": 50,
      "total_items": 1,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  }
  ```

  ```json Status: Completed (Mixed Results) theme={null}
  {
    "status": "completed",
    "progress": {
      "products_processed": 3,
      "urls_completed": 3,
      "total_urls": 3,
      "percent_complete": 100
    },
    "error": null,
    "credits_used": 5,
    "results": {
      "products": [
        {
          "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."
        }
      ],
      "meta": {
        "total_requested": 3,
        "total_successful": 1,
        "total_failed": 1,
        "total_failed_by_reason": {
          "automated_access_not_permitted": 1
        },
        "total_invalid": 1,
        "total_invalid_by_reason": {
          "non_product_url": 1
        },
        "total_pending": 0
      }
    },
    "pagination": {
      "page": 1,
      "limit": 50,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  }
  ```

  ```json Status: Running theme={null}
  {
    "status": "running",
    "progress": {
      "products_processed": 45,
      "urls_completed": 45,
      "total_urls": 100,
      "percent_complete": 45
    },
    "error": null,
    "results": {
      "meta": {
        "total_requested": 100,
        "total_successful": 40,
        "total_failed": 3,
        "total_failed_by_reason": {
          "automated_access_not_permitted": 2,
          "other": 1
        },
        "total_invalid": 2,
        "total_invalid_by_reason": {
          "non_product_url": 1,
          "malformed_url": 1
        },
        "total_pending": 55
      }
    }
  }
  ```

  ```json Status: Failed theme={null}
  {
    "status": "failed",
    "progress": {
      "products_processed": 12,
      "urls_completed": 12,
      "total_urls": 100,
      "percent_complete": 12
    },
    "error": "The operation failed. Please retry or contact support with this execution ID.",
    "results": {
      "meta": {
        "total_requested": 100,
        "total_successful": 8,
        "total_failed": 3,
        "total_failed_by_reason": {
          "automated_access_not_permitted": 2,
          "other": 1
        },
        "total_invalid": 1,
        "total_invalid_by_reason": {
          "non_product_url": 1
        },
        "total_pending": 88
      }
    }
  }
  ```
</ResponseExample>

## Polling Strategy

For best results when waiting for completion:

1. **Initial Poll:** Check status immediately after receiving `execution_id`
2. **Polling Interval:** Wait 5-10 seconds between polls for running executions
3. **Exponential Backoff:** Consider increasing wait time for long-running jobs
4. **Timeout:** Set a maximum wait time based on your batch size