> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parallel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopping search

> Shopping search for products to buy, each linked to a store's product page.



## OpenAPI

````yaml /public-openapi.json post /v1/shopping/search
openapi: 3.1.0
info:
  title: Parallel API
  description: Parallel API
  contact:
    name: Parallel Support
    url: https://parallel.ai
    email: support@parallel.ai
  version: 0.1.2
servers:
  - url: https://api.parallel.ai
    description: Parallel API
security:
  - ApiKeyAuth: []
tags:
  - name: Search
    description: >-
      Search returns ranked URLs with extended excerpts suitable for LLM
      consumption. Inputs are a natural-language objective and optional keyword
      queries. Source policies allow including or excluding specific domains and
      have configurable output sizes. The returned extended snippets contain
      dense, relevant information from relevant pages.

      - Result: ranked list with URL, title, and long text excerpts


      Images, Places, Shopping, Hotels and Flights return typed results for one
      kind of content.

      - The Images API returns ranked images from the web. Inputs are keyword
      queries and an optional natural-language objective. `fast`: lowest latency
      and cost. `advanced` (default): slower, with higher-quality results.
      Result: title, direct image URL, source page URL, and dimensions.

      - The Places API finds places such as restaurants, shops and attractions
      near a location. Inputs are a query, and a location name or coordinates.
      `fast`: lowest latency, with fewer results. `advanced` (default): slower,
      with more complete results. Result: name, website, address, phone,
      coordinates, rating tier, price level, and opening hours.

      - The Shopping API finds products for sale at online stores. Inputs are
      keyword queries, an optional natural-language objective, and optional
      price and condition filters. Result: title, store page URL, merchant,
      price, rating, availability, and other stores' offers.

      - The Hotels API finds hotels and vacation rentals with live prices.
      Inputs are a location, check-in and check-out dates, and guests, with
      optional price, rating and star class filters. Result: name, website or
      booking page, address, coordinates, star class, rating tier, nightly and
      total price, and each seller's offer.

      - The Flights API finds itineraries with live fares. Inputs are origin and
      destination airports, travel dates, and passengers, with optional cabin,
      stop, price, airline and time filters. Result: total price, a booking
      link, and each leg's flights, times, stops and layovers.
  - name: Extract
    description: >-
      Extract returns excerpts or full content from one or more URLs. Inputs are
      a list of URLs and an optional search objective and keyword queries. The
      returned excerpts or full content is formatted as markdown and suitable
      for LLM consumption.

      - Result: excerpts or full content from the URL formatted as markdown
  - name: Decisions
    description: >-
      Answer typed choice, score, and probability questions using current web
      evidence, with shared citations for the request.
  - name: Tasks
    description: >-
      The Task API executes web research and extraction tasks. Clients submit a
      natural-language objective with an optional input schema; the service
      plans retrieval, fetches relevant URLs, and returns outputs that conform
      to a provided or inferred JSON schema. Supports deep research style
      queries and can return rich structured JSON outputs. Processors trade-off
      between cost, latency, and quality. Each processor supports calibrated
      confidences.

      - Output metadata: citations, excerpts, reasoning, and confidence per
      field


      Task Groups enable batch execution of many independent Task runs with
      group-level monitoring and failure handling.

      - Submit hundreds or thousands of Tasks as a single group

      - Observe group progress and receive results as they complete

      - Real-time updates via Server-Sent Events (SSE)

      - Add tasks to an existing group while it is running

      - Group-level retry and error aggregation
  - name: FindAll
    description: >-
      The FindAll API discovers and evaluates entities that match complex
      criteria from natural language objectives. Submit a high-level goal and
      the service automatically generates structured match conditions, discovers
      relevant candidates, and evaluates each against the criteria. Returns
      comprehensive results with detailed reasoning, citations, and confidence
      scores for each match decision. Streaming events and webhooks are
      supported.
  - name: Monitor
    description: >-
      The Monitor API watches the web for material changes on a fixed frequency.
      Each monitor runs once on creation and then on its configured schedule,
      emitting events when meaningful changes are detected.

      - `event_stream` monitors track a search query and emit an event for each
      new material change.

      - `snapshot` monitors track a specific task run's output and emit an event
      when the output changes.


      Results can be polled via the events endpoint or delivered via webhooks.
  - name: Memory
    description: >-
      The Memory API retrieves and manages memories created by Tasks, Monitors,
      and FindAll runs. Memories can be personal or isolated with a
      `memory_scope_key`.
  - name: Chat API (Beta)
    description: >-
      The Chat API provides a programmatic chat-style text generation interface.
      It accepts a sequence of messages and returns model responses. Intended
      for assistant-like interactions and evaluation. Streaming responses are
      supported.
  - name: Responses API
    description: >-
      An OpenAI-Responses-compatible interface for answers grounded in live web
      research, with URL citations. Point any Responses-API client — the OpenAI
      Python SDK, OpenAI TypeScript SDK, the Agents SDK, or raw HTTP — at
      `https://api.parallel.ai` with your Parallel API key, set `model` to
      `parallel`, and call `/v1/responses`.

      - `input` accepts a plain string or an array of role/content messages
      (canonical OpenAI shape; text content only).

      - `reasoning.effort` (`low`/`medium`/`high`/`auto`) controls how much
      research is performed, trading response time for answer quality.

      - Multi-turn via `previous_response_id`.

      - Structured outputs via `text.format = {"type": "json_schema", "name":
      ..., "schema": {...}}`.

      - Streaming (`stream=true`) emits the standard OpenAI Responses SSE
      lifecycle: `response.created` and `response.in_progress`, then output item
      / content part / text delta events with URL-citation annotations, the
      matching `*.done` events, and a terminal `response.completed` — or
      `response.failed` if the request fails mid-stream.
paths:
  /v1/shopping/search:
    post:
      tags:
        - Search
      summary: Shopping search
      description: >-
        Shopping search for products to buy, each linked to a store's product
        page.
      operationId: product_search_v1_shopping_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSearchResponse'
        '422':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                type: error
                error:
                  ref_id: search_fcb2b4f3c75e418687bccaa1a8381331
                  message: Request validation error
components:
  schemas:
    ProductSearchRequest:
      properties:
        search_queries:
          items:
            type: string
            maxLength: 200
          type: array
          maxItems: 5
          title: Search Queries
          description: >-
            Keyword product queries, such as a model name or a product type with
            its attributes. At least one query is required, and at most 5, each
            at most 200 characters.
          examples:
            - - Sony WH-1000XM5
            - - waterproof hiking boots women
        objective:
          anyOf:
            - type: string
            - type: 'null'
          title: Objective
          description: >-
            Natural-language description of the products wanted, used with
            search_queries to focus results. At most 5000 characters.
        min_price:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Min Price
          description: >-
            Only products priced at least this, in the market's currency.
            Products without a known price are left out.
        max_price:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          title: Max Price
          description: >-
            Only products priced at most this, in the market's currency.
            Products without a known price are left out.
        condition:
          anyOf:
            - type: string
              enum:
                - new
                - used
                - refurbished
            - type: string
              const: any
          title: Condition
          description: >-
            `new` (default), `used`, `refurbished` or `any`. Leaves out products
            known to be in another condition; most stores do not state one, so
            for `used` or `refurbished` also say it in the queries.
          default: new
        mode:
          anyOf:
            - type: string
              enum:
                - advanced
            - type: 'null'
          title: Mode
          description: '`advanced` (default): live store listings from many sources.'
        session_id:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Session Id
          description: >-
            Session identifier that groups related calls made as part of a
            larger task. Echoed back in the response when nonempty; generated by
            the server if omitted, null, or empty.
        client_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Model
          description: The model generating this request and consuming the results.
          examples:
            - claude-opus-4-7
            - gpt-5.4
            - gemini-3.1-pro
        advanced_settings:
          anyOf:
            - $ref: '#/components/schemas/AdvancedProductSearchSettings'
            - type: 'null'
          description: Advanced configuration for market and result count.
      additionalProperties: false
      type: object
      required:
        - search_queries
      title: ProductSearchRequest
      description: 'Shopping search request: products to buy, each linked to a store''s page.'
    ProductSearchResponse:
      properties:
        search_id:
          type: string
          title: Search Id
          description: 'Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7`'
        session_id:
          type: string
          title: Session Id
          description: >-
            Session identifier, echoed back from the request when nonempty;
            otherwise generated by the server. Pass it to later calls made as
            part of the same task.
          examples:
            - session_8a911eb27c7a4afaa20d0d9dc98d07c0
        results:
          items:
            $ref: '#/components/schemas/ProductSearchResult'
          type: array
          title: Results
          description: >-
            Products by decreasing relevance, in three groups: distinct
            products, then one seller's other options of an earlier product,
            then products that are out of stock.
        warnings:
          anyOf:
            - items:
                $ref: '#/components/schemas/Warning'
              type: array
            - type: 'null'
          title: Warnings
          description: Warnings for the search request, if any.
        usage:
          anyOf:
            - items:
                $ref: '#/components/schemas/UsageItem'
              type: array
            - type: 'null'
          title: Usage
          description: Usage metrics for the search request.
      type: object
      required:
        - search_id
        - session_id
        - results
      title: ProductSearchResponse
      description: Shopping search response.
    ErrorResponse:
      properties:
        type:
          type: string
          const: error
          title: Type
          description: Always 'error'.
        error:
          $ref: '#/components/schemas/Error'
          description: Error.
      type: object
      required:
        - type
        - error
      title: ErrorResponse
      description: Response object used for non-200 status codes.
    AdvancedProductSearchSettings:
      properties:
        max_results:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Results
          description: >-
            Upper bound on results. Defaults to 20; values above the mode's
            maximum are reduced to it, with a warning.
        location:
          anyOf:
            - type: string
            - type: 'null'
          title: Location
          description: >-
            ISO 3166-1 alpha-2 country of the shopper's market. Sets the stores
            searched and the currency of prices. Defaults to `us`.
          examples:
            - us
            - gb
            - de
            - jp
      additionalProperties: false
      type: object
      title: AdvancedProductSearchSettings
      description: Advanced shopping search configuration.
    ProductSearchResult:
      properties:
        url:
          type: string
          title: Url
          description: The store's product page.
        title:
          type: string
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: What the product is and its main specifications.
        merchant:
          anyOf:
            - type: string
            - type: 'null'
          title: Merchant
          description: The store's name.
        brand:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand
        price:
          anyOf:
            - type: number
            - type: 'null'
          title: Price
          description: Price at the store when it was retrieved.
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
          description: ISO 4217 code.
        original_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Original Price
          description: Price before a discount, when the product is on sale.
        rating:
          anyOf:
            - type: number
            - type: 'null'
          title: Rating
          description: Average rating out of 5.
        review_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Review Count
          description: Reviews behind `rating`.
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        condition:
          anyOf:
            - type: string
              enum:
                - new
                - used
                - refurbished
            - type: 'null'
          title: Condition
          description: '`new`, `used` or `refurbished`, when known.'
        availability:
          anyOf:
            - type: string
              enum:
                - in_stock
                - out_of_stock
                - preorder
            - type: 'null'
          title: Availability
          description: '`in_stock`, `out_of_stock` or `preorder`, when known.'
        offers:
          items:
            $ref: '#/components/schemas/ProductOffer'
          type: array
          title: Offers
          description: Other stores' pages for the same product, when known.
      type: object
      required:
        - url
        - title
      title: ProductSearchResult
      description: One product at one store, linked to the store's product page.
    Warning:
      properties:
        type:
          type: string
          enum:
            - spec_validation_warning
            - input_validation_warning
            - warning
          title: Type
          description: >-
            Type of warning. Note that adding new warning types is considered a
            backward-compatible change.
          examples:
            - spec_validation_warning
            - input_validation_warning
        message:
          type: string
          title: Message
          description: Human-readable message.
        detail:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Detail
          description: Optional detail supporting the warning.
      type: object
      required:
        - type
        - message
      title: Warning
      description: Human-readable message for a task.
    UsageItem:
      properties:
        name:
          type: string
          title: Name
          description: Name of the SKU.
          examples:
            - sku_search
            - sku_extract_excerpts
        count:
          type: integer
          title: Count
          description: Count of the SKU.
          examples:
            - 1
      type: object
      required:
        - name
        - count
      title: UsageItem
      description: Usage item for a single operation.
    Error:
      properties:
        ref_id:
          type: string
          title: Reference ID
          description: Reference ID for the error.
        message:
          type: string
          title: Message
          description: Human-readable message.
        detail:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Detail
          description: Optional detail supporting the error.
      type: object
      required:
        - ref_id
        - message
      title: Error
      description: An error message.
    ProductOffer:
      properties:
        url:
          type: string
          title: Url
          description: The store's product page.
        merchant:
          anyOf:
            - type: string
            - type: 'null'
          title: Merchant
          description: The store's name.
        price:
          anyOf:
            - type: number
            - type: 'null'
          title: Price
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
          description: ISO 4217 code.
      type: object
      required:
        - url
      title: ProductOffer
      description: Another store's page for the same product.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````