Skip to main content
GET
https://api.getcatalog.ai
/
v2
/
agentic-search
/
{execution_id}
# Check execution status
curl -X GET "https://api.getcatalog.ai/v2/agentic-search/agentic-a1b2c3d4-1735123456789" \
  -H "x-api-key: $CATALOG_API_KEY"

{
  "execution_id": "agentic-a1b2c3d4-1735123456789",
  "status": "running",
  "error": null,
  "meta": {
    "query": "A Barbour jacket suitable for the office",
    "progress": {
      "products_processed": 0,
      "products_total": 8,
      "percent_complete": 0
    },
    "start_date": "2025-01-15T10:30:00.000Z",
    "stop_date": null,
    "duration_ms": 15000
  }
}
When to use: After starting a search job with the POST endpoint, use this endpoint to:
  • Check if the search is complete
  • Monitor real-time progress
  • Get detailed metrics including products found
  • Retrieve paginated product results when processing completes
  • Track execution timing and duration
Authentication Required: This endpoint requires a valid API key. Execution IDs are scoped to your organization - you can only access executions that belong to your organization.Cancel Running Executions: If you need to stop a search that is currently running, use DELETE /v2/agentic-search/{execution_id} to stop the execution.

​
Request

​
x-api-key
string
required
Your API key for authentication
​
execution_id
string
required
The execution ID returned from POST /v2/agentic-searchFormat: agentic-{uuid}-{timestamp}Note: If the execution ID does not exist or does not belong to your organization, the endpoint returns a 404 Not Found error.

​
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

​
Response

​
execution_id
string
The execution identifier
​
status
string
Current execution statusPossible 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
​
error
string | null
Error message if the execution failed, otherwise null
​
data
array
Array of products matching the search query with comprehensive product information (only present when status is “completed”, up to 8 products). Fewer products may be returned if some cannot be processed or don’t meet quality requirements.
​
pagination
object
Pagination metadata for the results (only present when status is “completed” and data is returned)
​
meta
object
Detailed metadata about the execution
# Check execution status
curl -X GET "https://api.getcatalog.ai/v2/agentic-search/agentic-a1b2c3d4-1735123456789" \
  -H "x-api-key: $CATALOG_API_KEY"

{
  "execution_id": "agentic-a1b2c3d4-1735123456789",
  "status": "running",
  "error": null,
  "meta": {
    "query": "A Barbour jacket suitable for the office",
    "progress": {
      "products_processed": 0,
      "products_total": 8,
      "percent_complete": 0
    },
    "start_date": "2025-01-15T10:30:00.000Z",
    "stop_date": null,
    "duration_ms": 15000
  }
}

​
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 searches
  4. Timeout: Set a maximum wait time based on your application’s requirements
  5. Progress Tracking: Monitor meta.progress to see real-time progress
  6. Cancellation: If a search is taking too long or you need to stop it, use DELETE /v2/agentic-search/{execution_id} to stop running executions