> ## 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.

# Agentic Search

> Async AI-powered search with customer profile personalization. Returns immediately with an execution_id to check status and retrieve results.

<Tip>
  **When to use:** Best for personalized shopping experiences where you have customer profile data and need comprehensive product information. For faster searches with up to 10 results, use [`POST /v2/agentic-search-mini`](/v2/api-reference/endpoints/search/agentic-search-mini).
</Tip>

<Note>
  **Async Processing:** This endpoint starts processing asynchronously and returns an `execution_id` immediately. Use [`GET /v2/agentic-search/{execution_id}`](/v2/api-reference/endpoints/search/get-agentic-search-status) to check progress and retrieve results when processing completes.

  **View All Executions:** You can view all your agentic search executions using [`GET /v2/agentic-search`](/v2/api-reference/endpoints/search/list-agentic-search-executions) to see all search jobs, their statuses, and when they were created.

  **Cancel Execution:** You can cancel a running agentic search execution using [`DELETE /v2/agentic-search/{execution_id}`](/v2/api-reference/endpoints/search/cancel-agentic-search-execution) if you need to stop a search that is currently processing.
</Note>

## Request

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

### Request Body

<ParamField body="query" type="string" required>
  Natural language search query for product discovery

  **Examples:**

  * `"performance activewear for HIIT workouts in humid climates"`
  * `"versatile capsule wardrobe pieces for European business travel"`
  * `"statement jewelry that complements a maximalist aesthetic"`
</ParamField>

<ParamField body="customer_profile" type="object" optional>
  Optional customer profile information to personalize search results. This field accepts any JSON structure, allowing you to provide custom customer attributes and preferences.

  **Common Structure:**

  ```json theme={null}
  {
    "style": {
      "fit": "string",
      "color": "string",
      "aesthetic": ["string"],
      "silhouette": ["string"],
      "avoid": ["string"]
    },
    "preferences": {
      "in_stock_only": boolean,
      "comfort_priority": boolean
    },
    "usage_context": {
      "activities": ["string"],
      "environment": "string",
      "travel_friendly": boolean,
      "durability_priority": boolean
    },
    "purchase_behavior": {
      "value": "string",
      "buying_frequency": "string"
    }
  }
  ```
</ParamField>

## Response

<ResponseField name="execution_id" type="string">
  Unique execution identifier for this search job. Use this ID with [`GET /v2/agentic-search/{execution_id}`](/v2/api-reference/endpoints/search/get-agentic-search-status) to check progress and retrieve results.

  **Format:** `agentic-{uuid}-{timestamp}`
</ResponseField>

<ResponseField name="status" type="string">
  Initial execution status. Always `"pending"` when the search is first started.
</ResponseField>

<ResponseField name="meta" type="object">
  Metadata about the request

  <Expandable title="Meta Object">
    <ResponseField name="credits_used" type="number">
      Number of credits charged for starting this search operation
    </ResponseField>

    <ResponseField name="request_id" type="string" optional>
      Unique request identifier for support purposes (also available in the `Request-ID` response header)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample dropdown>
  ```powershell cURL theme={null}
  curl -X POST https://api.getcatalog.ai/v2/agentic-search \
    -H "Content-Type: application/json" \
    -H "x-api-key: $CATALOG_API_KEY" \
    -d '{
      "query": "A Barbour jacket suitable for the office",
      "customer_profile": {
        "style": {
          "fit": "casual with a refined, creative edge",
          "avoid": [
            "large logos",
            "loud streetwear",
            "technical performancewear"
          ],
          "color": "prefers earth tones, neutrals, black",
          "aesthetic": [
            "minimal and cool"
          ],
          "silhouette": [
            "relaxed",
            "cropped",
            "unstructured"
          ]
        },
        "preferences": {
          "in_stock_only": true,
          "comfort_priority": true
        },
        "usage_context": {
          "activities": [
            "office",
            "coffee runs",
            "after-work events"
          ],
          "environment": "urban, mild climate",
          "travel_friendly": true,
          "durability_priority": true
        },
        "purchase_behavior": {
          "value": "distinctive, expressive pieces",
          "buying_frequency": "occasional, style-driven"
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.getcatalog.ai/v2/agentic-search', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      query: 'A popular Barbour jacket to wear to the office',
      customer_profile: {
        style: {
          fit: 'elevated casual with artistic flair',
          avoid: [
            'flashy logos',
            'overt streetwear',
            'overly techy sportswear'
          ],
          color: 'prefers earth tones, neutrals, and black',
          aesthetic: [
            'understated cool'
          ],
          silhouette: [
            'loose',
            'cropped',
            'unstructured'
          ]
        },
        preferences: {
          in_stock_only: true,
          comfort_priority: true
        },
        usage_context: {
          activities: [
            'office',
            'coffee runs',
            'after work events'
          ],
          environment: 'urban, temperate climate',
          travel_friendly: true,
          durability_priority: true
        },
        purchase_behavior: {
          value: 'unique and expressive pieces',
          buying_frequency: 'occasional, style-driven purchases'
        }
      }
    })
  });

  const data = await response.json();
  console.log(`Search started with execution ID: ${data.execution_id}`);
  console.log(`Credits used: ${data.meta.credits_used}`);

  // Poll for results: GET /v2/agentic-search/{execution_id}
  ```

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

  response = requests.post(
      'https://api.getcatalog.ai/v2/agentic-search',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY'
      },
      json={
          'query': 'A popular Barbour jacket to wear to the office',
          'customer_profile': {
              'style': {
                  'fit': 'elevated casual with artistic flair',
                  'avoid': [
                      'flashy logos',
                      'overt streetwear',
                      'overly techy sportswear'
                  ],
                  'color': 'prefers earth tones, neutrals, and black',
                  'aesthetic': [
                      'understated cool'
                  ],
                  'silhouette': [
                      'loose',
                      'cropped',
                      'unstructured'
                  ]
              },
              'preferences': {
                  'in_stock_only': True,
                  'comfort_priority': True
              },
              'usage_context': {
                  'activities': [
                      'office',
                      'coffee runs',
                      'after work events'
                  ],
                  'environment': 'urban, temperate climate',
                  'travel_friendly': True,
                  'durability_priority': True
              },
              'purchase_behavior': {
                  'value': 'unique and expressive pieces',
                  'buying_frequency': 'occasional, style-driven purchases'
              }
          }
      }
  )

  data = response.json()
  execution_id = data['execution_id']
  print(f"Search started with execution ID: {execution_id}")
  print(f"Credits used: {data['meta']['credits_used']}")

  # Poll for results: GET /v2/agentic-search/{execution_id}
  ```
</RequestExample>

<ResponseExample>
  ```json POST Response (202 Accepted) theme={null}
  {
    "execution_id": "agentic-a1b2c3d4-1735123456789",
    "status": "pending",
    "meta": {
      "credits_used": 25
    }
  }
  ```
</ResponseExample>

## Response Schema and Enable Flags

The `/v2/agentic-search` endpoint maintains a consistent response schema regardless of `enable_*` flag values. When you retrieve results via GET status, all fields are always present in the `product` object of each item in the `data` array, but will be `null` when the corresponding flag is `false`.

**Field Mappings:**

| Flag                | Affected Fields                                                                            |
| :------------------ | :----------------------------------------------------------------------------------------- |
| `enable_enrichment` | `attributes`, `product_type`, `google_product_category_id`, `google_product_category_path` |