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

# Amazon research

> Search products, inspect an ASIN, read term-level demand, filtered review pages, history and merchant offers, including optional Shopping search and merchant page reads.

Specify the marketplace. Actions: search, product, keywords, keyword\_volume, reviews, price\_history offers, merchant\_search and merchant\_page. Quote the intended request; max\_charge\_usd rejects an over-budget Run before admission. Unknown values stay null. Record observed review pages and filters; a filtered sample is not population prevalence. Prices and shipping retain their defined series, currency and observation time. Cached offers are not verified checkout prices. Read the same authenticated result\_url for pending results. Native evidence stays on each Run.


## OpenAPI

````yaml /openapi.json post /v1/solutions/gtm/amazon_research
openapi: 3.1.0
info:
  title: Glasser
  version: 0.0.1
  description: >-
    One key, no contract, pay per call, across paid APIs bought wholesale. Every
    response carries x-request-id; every error body carries the same envelope.
servers:
  - url: https://api.glasser.ai
security: []
tags:
  - name: Solutions
  - name: Endpoints
  - name: Runs
  - name: Balance
paths:
  /v1/solutions/gtm/amazon_research:
    post:
      tags:
        - Solutions
      summary: Amazon research
      description: >-
        Search Amazon products, inspect an exact ASIN, retrieve related or
        exact-term demand estimates, collect bounded filtered review pages, or
        read historical prices and separate merchant-offer observations. Require
        an explicit marketplace. Missing fields remain null; estimates, review
        samples and unavailable prices retain their evidence limits. Unsupported
        fields and requests exceeding max_charge_usd fail before a Run. HTTP 202
        returns a signed, authenticated result_url to read the same Runs without
        another Charge. Provider-native output remains on GET /v1/runs/:id.
        provider=auto falls back only on Provider errors, timeouts or admission
        503, never on an empty result.
      operationId: gtm-amazon-research
      parameters:
        - name: idempotency-key
          in: header
          schema:
            type: string
            minLength: 1
            description: >-
              Generate a new unique value (prefer a random UUID) for each
              independent lookup, even with identical parameters on the same
              day. Retry the same intended execution with its original key and
              parameters to retrieve the original Run without another Charge.
              Changing execution parameters with the same key returns 409;
              changing task_id or metadata does not start a new Run. Existing
              opaque keys remain valid for recovery.
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum:
                    - search
                    - product
                    - keywords
                    - keyword_volume
                    - reviews
                    - price_history
                    - offers
                    - merchant_search
                    - merchant_page
                country:
                  type: string
                  minLength: 1
                  description: >-
                    Explicit Amazon marketplace country. Supported: us, gb, de,
                    fr, it, es, ca, jp, in, au. Related keywords supports us/en
                    only; exact keyword_volume has its own exposed
                    locale/language pairs.
                provider:
                  anyOf:
                    - type: string
                      enum:
                        - auto
                        - serpapi
                        - dataforseo
                        - apify
                        - keepa
                        - serper
                      description: >-
                        Default auto: select the first eligible Provider in
                        Glasser's preference order. A named Provider must
                        support the request and be allowed by your Key; it does
                        not fall back to another Provider. Available values are
                        listed below.
                    - type: 'null'
                max_charge_usd:
                  anyOf:
                    - type: string
                      pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
                      description: >-
                        Exact USD decimal string (min 2, max 6 decimals, one
                        canonical spelling). Sum with decimal arithmetic or
                        scale by 10^6 — never floats.
                      maxLength: 20
                    - type: 'null'
                review_pages:
                  anyOf:
                    - type: integer
                      minimum: 1
                      maximum: 10
                    - type: 'null'
                review_rating:
                  anyOf:
                    - type: integer
                      minimum: 1
                      maximum: 5
                    - type: 'null'
                review_sort:
                  anyOf:
                    - type: string
                      enum:
                        - recent
                        - helpful
                    - type: 'null'
                verified_only:
                  anyOf:
                    - type: boolean
                    - type: 'null'
                review_keyword:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 200
                    - type: 'null'
                url:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 2048
                      pattern: ^https?:\/\/
                    - type: 'null'
                query:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 200
                    - type: 'null'
                keywords:
                  anyOf:
                    - type: array
                      items:
                        type: string
                        minLength: 1
                      minItems: 1
                      maxItems: 1000
                    - type: 'null'
                asin:
                  anyOf:
                    - type: string
                      pattern: ^[A-Z0-9]{10}$
                    - type: 'null'
                page:
                  anyOf:
                    - type: integer
                      minimum: 1
                      maximum: 20
                    - type: 'null'
                limit:
                  anyOf:
                    - type: integer
                      minimum: 1
                      maximum: 100
                    - type: 'null'
                offset:
                  anyOf:
                    - type: integer
                      minimum: 0
                      maximum: 10000
                    - type: 'null'
                language:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: 'null'
                days:
                  anyOf:
                    - type: integer
                      minimum: 1
                    - type: 'null'
                task_id:
                  anyOf:
                    - type: string
                      description: >-
                        Group related Runs, including automatic fallback, under
                        one Task. Reuse a stable string and filter the Runs list
                        by task to retrieve them.
                    - type: 'null'
                metadata:
                  anyOf:
                    - anyOf:
                        - type: object
                          additionalProperties:
                            type: string
                            minLength: 1
                            maxLength: 500
                          maxProperties: 20
                          propertyNames:
                            type: string
                            pattern: ^[a-z][a-z0-9_]{0,39}$
                        - {}
                      description: >-
                        Optional tracking fields, returned on the Run and
                        available as filters. They never go to the Provider or
                        affect routing, Price, or idempotency.


                        - Up to 20 keys: lowercase letters, digits, and
                        underscores; start with a letter; at most 40 characters.

                        - Values: strings of 1–500 characters.

                        - user_id: your End user's opaque ID, never their email
                        address or name.


                        Invalid entries are dropped whole, not truncated. The
                        request continues, and the Run returns the fields that
                        were stored.
                    - type: 'null'
              required:
                - action
                - country
              additionalProperties: false
              description: >-
                merchant_search: query, optional language; merchant_page: exact
                public url; search: query and optional page;
                product/reviews/offers: exact asin; reviews supports bounded
                review_pages, review_rating, review_sort, verified_only and
                review_keyword; keywords: query, optional language/limit/offset
                (us/en only); keyword_volume: explicit keywords and language;
                max_charge_usd rejects requests exceeding the caller cap before
                creating a Run; price_history: exact asin and optional days
                (default 180). Unsupported fields are rejected before charging.
                No listing edits, fee estimates or recurring monitoring.
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AmazonResearchResult'
        '202':
          description: Success
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AmazonResearchResult'
        '400':
          description: ValidationFailed | IdempotencyKeyRequired
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
                  - $ref: '#/components/schemas/IdempotencyKeyRequiredEncoded'
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedEncoded'
        '402':
          description: InsufficientBalance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientBalanceEncoded'
        '403':
          description: EndpointNotPermitted | Forbidden
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/EndpointNotPermittedEncoded'
                  - $ref: '#/components/schemas/ForbiddenEncoded'
        '409':
          description: IdempotencyConflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdempotencyConflictEncoded'
        '429':
          description: RateLimited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedEncoded'
        '503':
          description: ServiceUnavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableEncoded'
      security:
        - bearer: []
components:
  schemas:
    AmazonResearchResult:
      type: object
      properties:
        id:
          type: string
        run_url:
          type: string
          description: Open this Run in the console. Requires Workspace membership.
        provider:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]*$
        endpoint:
          type: string
          pattern: ^\/.+$
        endpoint_version:
          type: integer
          exclusiveMinimum: 0
        status:
          type: string
          enum:
            - QUEUED
            - RUNNING
            - COMPLETED
            - FAILED
            - STOPPED
          description: >-
            QUEUED or RUNNING: still in progress. COMPLETED: a Provider response
            is available, including non-2xx responses. FAILED: read failure.
            STOPPED: stopped before dispatch. Read charge_usd separately from
            status.
        failure:
          anyOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - TIMED_OUT
                    - INTERNAL
                message:
                  type: string
              required:
                - kind
                - message
              additionalProperties: false
            - type: 'null'
          description: Why the Run failed. Non-null only when status is FAILED.
        input:
          anyOf:
            - type: object
            - type: array
              items:
                type: object
        output:
          anyOf:
            - anyOf:
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          asin:
                            anyOf:
                              - type: string
                              - type: 'null'
                          title:
                            anyOf:
                              - type: string
                              - type: 'null'
                          url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          brand:
                            anyOf:
                              - type: string
                              - type: 'null'
                          image_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          price:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          price_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                          currency:
                            anyOf:
                              - type: string
                              - type: 'null'
                          rating:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          reviews:
                            anyOf:
                              - type: integer
                              - type: 'null'
                            description: >-
                              Provider-reported displayed review total; may
                              aggregate variants. Not the collected review
                              sample size.
                          position:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          sponsored:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                          bought_past_month_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                          stock_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                          condition_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                          price_basis:
                            type: string
                            enum:
                              - displayed_listing_price
                          variants:
                            type: array
                            items:
                              type: object
                              properties:
                                asin:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                label:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                selected:
                                  anyOf:
                                    - type: boolean
                                    - type: 'null'
                              required:
                                - asin
                                - label
                                - selected
                              additionalProperties: false
                          attributes:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                value:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                              required:
                                - name
                                - value
                              additionalProperties: false
                        required:
                          - asin
                          - title
                          - url
                          - brand
                          - image_url
                          - price
                          - price_text
                          - currency
                          - rating
                          - reviews
                          - position
                          - sponsored
                          - bought_past_month_text
                          - stock_text
                          - condition_text
                          - price_basis
                          - variants
                          - attributes
                        additionalProperties: false
                    amazon_domain:
                      anyOf:
                        - type: string
                        - type: 'null'
                    total_matches:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    next_page:
                      anyOf:
                        - type: integer
                        - type: 'null'
                  required:
                    - items
                    - amazon_domain
                    - total_matches
                    - next_page
                  additionalProperties: false
                - type: object
                  properties:
                    product:
                      type: object
                      properties:
                        asin:
                          anyOf:
                            - type: string
                            - type: 'null'
                        title:
                          anyOf:
                            - type: string
                            - type: 'null'
                        url:
                          anyOf:
                            - type: string
                            - type: 'null'
                        brand:
                          anyOf:
                            - type: string
                            - type: 'null'
                        image_url:
                          anyOf:
                            - type: string
                            - type: 'null'
                        price:
                          anyOf:
                            - anyOf:
                                - type: number
                                - type: string
                                  enum:
                                    - Infinity
                                    - '-Infinity'
                                    - NaN
                            - type: 'null'
                        price_text:
                          anyOf:
                            - type: string
                            - type: 'null'
                        currency:
                          anyOf:
                            - type: string
                            - type: 'null'
                        rating:
                          anyOf:
                            - anyOf:
                                - type: number
                                - type: string
                                  enum:
                                    - Infinity
                                    - '-Infinity'
                                    - NaN
                            - type: 'null'
                        reviews:
                          anyOf:
                            - type: integer
                            - type: 'null'
                          description: >-
                            Provider-reported displayed review total; may
                            aggregate variants. Not the collected review sample
                            size.
                        position:
                          anyOf:
                            - type: integer
                            - type: 'null'
                        sponsored:
                          anyOf:
                            - type: boolean
                            - type: 'null'
                        bought_past_month_text:
                          anyOf:
                            - type: string
                            - type: 'null'
                        stock_text:
                          anyOf:
                            - type: string
                            - type: 'null'
                        condition_text:
                          anyOf:
                            - type: string
                            - type: 'null'
                        price_basis:
                          type: string
                          enum:
                            - displayed_listing_price
                        variants:
                          type: array
                          items:
                            type: object
                            properties:
                              asin:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              label:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              selected:
                                anyOf:
                                  - type: boolean
                                  - type: 'null'
                            required:
                              - asin
                              - label
                              - selected
                            additionalProperties: false
                        attributes:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              value:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                            required:
                              - name
                              - value
                            additionalProperties: false
                      required:
                        - asin
                        - title
                        - url
                        - brand
                        - image_url
                        - price
                        - price_text
                        - currency
                        - rating
                        - reviews
                        - position
                        - sponsored
                        - bought_past_month_text
                        - stock_text
                        - condition_text
                        - price_basis
                        - variants
                        - attributes
                      additionalProperties: false
                    amazon_domain:
                      anyOf:
                        - type: string
                        - type: 'null'
                    purchase_options:
                      type: array
                      items:
                        type: object
                        properties:
                          condition:
                            anyOf:
                              - type: string
                              - type: 'null'
                          price:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          price_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                          stock_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                          seller_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - condition
                          - price
                          - price_text
                          - stock_text
                          - seller_text
                        additionalProperties: false
                  required:
                    - product
                    - amazon_domain
                    - purchase_options
                  additionalProperties: false
                - type: object
                  properties:
                    mode:
                      type: string
                      enum:
                        - related
                        - exact
                    location_code:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    language:
                      anyOf:
                        - type: string
                        - type: 'null'
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          keyword:
                            anyOf:
                              - type: string
                              - type: 'null'
                          dataforseo_search_volume:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          updated_at:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - keyword
                          - dataforseo_search_volume
                          - updated_at
                        additionalProperties: false
                    total_matches:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    next_offset:
                      anyOf:
                        - type: integer
                        - type: 'null'
                  required:
                    - mode
                    - location_code
                    - language
                    - items
                    - total_matches
                    - next_offset
                  additionalProperties: false
                  description: >-
                    DataForSEO's estimated term-level Amazon search counts, not
                    sales. Overlapping terms must not be summed into market
                    size.
                - type: object
                  properties:
                    asin:
                      anyOf:
                        - type: string
                        - type: 'null'
                    amazon_domain:
                      anyOf:
                        - type: string
                        - type: 'null'
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            anyOf:
                              - type: string
                              - type: 'null'
                          url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          asin:
                            anyOf:
                              - type: string
                              - type: 'null'
                          title:
                            anyOf:
                              - type: string
                              - type: 'null'
                          text:
                            anyOf:
                              - type: string
                              - type: 'null'
                          rating:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          published_at:
                            anyOf:
                              - type: string
                              - type: 'null'
                          date_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                          verified_purchase:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                          vine:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                          language:
                            anyOf:
                              - type: string
                              - type: 'null'
                          helpful_votes:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          variation_asin:
                            anyOf:
                              - type: string
                              - type: 'null'
                          variant_attributes:
                            type: array
                            items:
                              type: string
                        required:
                          - id
                          - url
                          - asin
                          - title
                          - text
                          - rating
                          - published_at
                          - date_text
                          - verified_purchase
                          - vine
                          - language
                          - helpful_votes
                          - variation_asin
                          - variant_attributes
                        additionalProperties: false
                    sample_kind:
                      type: string
                      enum:
                        - recent_page
                        - filtered_pages
                    sampling:
                      type: object
                      properties:
                        requested_pages:
                          anyOf:
                            - type: integer
                            - type: 'null'
                        observed_pages:
                          type: array
                          items:
                            type: integer
                        sort:
                          anyOf:
                            - type: string
                            - type: 'null'
                        rating_filter:
                          anyOf:
                            - type: string
                            - type: 'null'
                        keyword_filter:
                          anyOf:
                            - type: string
                            - type: 'null'
                        reviewer_type:
                          anyOf:
                            - type: string
                            - type: 'null'
                        representative:
                          type: string
                          enum:
                            - not_established
                      required:
                        - requested_pages
                        - observed_pages
                        - sort
                        - rating_filter
                        - keyword_filter
                        - reviewer_type
                        - representative
                      additionalProperties: false
                    next_cursor:
                      type: 'null'
                  required:
                    - asin
                    - amazon_domain
                    - items
                    - sample_kind
                    - sampling
                    - next_cursor
                  additionalProperties: false
                  description: >-
                    Budget-bounded pages with optional
                    rating/keyword/verified-purchase filters. Observed pages are
                    reported separately from requested pages. No
                    representative-population claim. Review allegations remain
                    unverified.
                - type: object
                  properties:
                    updated_at:
                      anyOf:
                        - type: string
                        - type: 'null'
                    asin:
                      anyOf:
                        - type: string
                        - type: 'null'
                    title:
                      anyOf:
                        - type: string
                        - type: 'null'
                    amazon_domain:
                      anyOf:
                        - type: string
                        - type: 'null'
                    currency:
                      anyOf:
                        - type: string
                        - type: 'null'
                    series:
                      type: array
                      items:
                        type: object
                        properties:
                          price_type:
                            type: string
                            enum:
                              - AMAZON
                              - NEW
                              - LISTPRICE
                          points:
                            type: array
                            items:
                              type: object
                              properties:
                                observed_at:
                                  type: string
                                price:
                                  anyOf:
                                    - anyOf:
                                        - type: number
                                        - type: string
                                          enum:
                                            - Infinity
                                            - '-Infinity'
                                            - NaN
                                    - type: 'null'
                                available:
                                  type: boolean
                              required:
                                - observed_at
                                - price
                                - available
                              additionalProperties: false
                        required:
                          - price_type
                          - points
                        additionalProperties: false
                  required:
                    - updated_at
                    - asin
                    - title
                    - amazon_domain
                    - currency
                    - series
                  additionalProperties: false
                  description: >-
                    Keepa's separate price series. Unavailable observations have
                    price=null. NEW changed definition on 2026-02-23; do not
                    join baselines across that date. Historical observations are
                    not checkout quotes.
                - type: object
                  properties:
                    asin:
                      anyOf:
                        - type: string
                        - type: 'null'
                    title:
                      anyOf:
                        - type: string
                        - type: 'null'
                    amazon_domain:
                      anyOf:
                        - type: string
                        - type: 'null'
                    currency:
                      anyOf:
                        - type: string
                        - type: 'null'
                    updated_at:
                      anyOf:
                        - type: string
                        - type: 'null'
                    refresh_success:
                      anyOf:
                        - type: boolean
                        - type: 'null'
                    parent_asin:
                      anyOf:
                        - type: string
                        - type: 'null'
                    number_of_items:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    package_quantity:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    size:
                      anyOf:
                        - type: string
                        - type: 'null'
                    color:
                      anyOf:
                        - type: string
                        - type: 'null'
                    material:
                      anyOf:
                        - type: string
                        - type: 'null'
                    fee_context:
                      type: object
                      properties:
                        fulfillment_fee:
                          anyOf:
                            - anyOf:
                                - type: number
                                - type: string
                                  enum:
                                    - Infinity
                                    - '-Infinity'
                                    - NaN
                            - type: 'null'
                        updated_at:
                          anyOf:
                            - type: string
                            - type: 'null'
                        referral_fee_percent:
                          anyOf:
                            - anyOf:
                                - type: number
                                - type: string
                                  enum:
                                    - Infinity
                                    - '-Infinity'
                                    - NaN
                            - type: 'null'
                      required:
                        - fulfillment_fee
                        - updated_at
                        - referral_fee_percent
                      additionalProperties: false
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          seller_id:
                            anyOf:
                              - type: string
                              - type: 'null'
                          condition_code:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          condition_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                          is_amazon:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                          fulfilled_by_amazon:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                          last_seen_at:
                            anyOf:
                              - type: string
                              - type: 'null'
                          price_observed_at:
                            anyOf:
                              - type: string
                              - type: 'null'
                          price:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          shipping:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          landed_price:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                        required:
                          - seller_id
                          - condition_code
                          - condition_text
                          - is_amazon
                          - fulfilled_by_amazon
                          - last_seen_at
                          - price_observed_at
                          - price
                          - shipping
                          - landed_price
                        additionalProperties: false
                  required:
                    - asin
                    - title
                    - amazon_domain
                    - currency
                    - updated_at
                    - refresh_success
                    - parent_asin
                    - number_of_items
                    - package_quantity
                    - size
                    - color
                    - material
                    - fee_context
                    - items
                  additionalProperties: false
                  description: >-
                    Keepa's observed live-offer snapshot for this exact ASIN.
                    Numeric condition codes retain Keepa meaning; last-seen and
                    price-change times differ. Historical cached observations
                    are not a verified checkout quote. Competitor fees are
                    context, not the candidate SKU's cost.
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          title:
                            anyOf:
                              - type: string
                              - type: 'null'
                          url:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: The Google Shopping product page.
                          merchant_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              The merchant's offer URL when the Provider reports
                              one (SerpApi link); null for Serper.
                          google_product_id:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              Google Shopping catalog product id (Serper
                              productId, SerpApi product_id).
                          price_text:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              The Provider's display price, such as '$69.00'.
                              Not parsed; the currency follows country.
                          seller:
                            anyOf:
                              - type: string
                              - type: 'null'
                          rating:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                            description: Google's average star rating, 1–5.
                          reviews:
                            anyOf:
                              - type: integer
                              - type: 'null'
                            description: Number of Google reviews behind the rating.
                          image_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - title
                          - url
                          - merchant_url
                          - google_product_id
                          - price_text
                          - seller
                          - rating
                          - reviews
                          - image_url
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    url:
                      type: string
                      description: >-
                        The requested URL, or the final URL when the Provider
                        reports one.
                    final_url:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        The post-redirect URL as reported by the Provider
                        (Firecrawl, Exa). Null when the Provider does not report
                        one.
                    title:
                      anyOf:
                        - type: string
                        - type: 'null'
                    text:
                      anyOf:
                        - type: string
                        - type: 'null'
                    markdown:
                      anyOf:
                        - type: string
                        - type: 'null'
                    html:
                      anyOf:
                        - type: string
                        - type: 'null'
                    raw_html:
                      anyOf:
                        - type: string
                        - type: 'null'
                    text_character_limit:
                      anyOf:
                        - type: integer
                        - type: 'null'
                      description: >-
                        The character cap Glasser asked the Provider to apply to
                        text (10000 for Exa), so text of exactly this length may
                        be truncated. Null when no cap was applied.
                    cached:
                      anyOf:
                        - type: boolean
                        - type: 'null'
                      description: >-
                        Whether the Provider served the page from its cache
                        (Firecrawl cacheState, Exa status source). Null when the
                        Provider does not say.
                    fetched_at:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        When the Provider fetched the page, ISO 8601 UTC
                        (DataForSEO fetch_time). Null when the Provider does not
                        report it.
                    quality:
                      type: string
                      enum:
                        - unverified
                      description: >-
                        Deprecated: always 'unverified'; no content check is
                        applied. Kept for compatibility and will be removed in
                        the next breaking revision.
                  required:
                    - url
                    - final_url
                    - title
                    - text
                    - markdown
                    - html
                    - raw_html
                    - text_character_limit
                    - cached
                    - fetched_at
                    - quality
                  additionalProperties: false
            - type: 'null'
        response_file:
          type: object
          properties:
            body_field:
              type: string
              enum:
                - output
                - provider_response.error
            state:
              type: string
              enum:
                - available
                - link_pending
                - expired
                - unavailable
            download_url:
              anyOf:
                - type: string
                - type: 'null'
            link_expires_at:
              anyOf:
                - type: string
                  description: ISO-8601 UTC timestamp
                  format: date-time
                - type: 'null'
            file_expires_at:
              type: string
              description: ISO-8601 UTC timestamp
              format: date-time
            bytes:
              type: integer
              minimum: 0
            sha256:
              type: string
            content_type:
              type: string
              enum:
                - application/json
          required:
            - body_field
            - state
            - download_url
            - link_expires_at
            - file_expires_at
            - bytes
            - sha256
            - content_type
          additionalProperties: false
          description: >-
            Complete large Provider body, delivered as a JSON file. Glasser
            applies a 32 MiB runtime resource guard to captured bodies and
            serialized files. body_field identifies the replaced field; output
            is null or provider_response.error is omitted. Download URLs expire
            after at most one hour. Authenticated Get Run refreshes the URL
            while the file is available, for 7 days. Reads and downloads do not
            execute or charge another Run. If state is link_pending, read the
            same Run to prepare the link without another execution or charge.
            The URL grants temporary read access: share it only with intended
            recipients.
        provider_response:
          anyOf:
            - type: object
              properties:
                http_status:
                  type: integer
                  minimum: 100
                  maximum: 599
                  description: >-
                    HTTP status returned by the Provider. Check this even when
                    the Run is COMPLETED.
                error:
                  anyOf:
                    - {}
                    - type: 'null'
              required:
                - http_status
              additionalProperties: false
            - type: 'null'
          description: >-
            Non-null only when status is COMPLETED.


            - For 2xx responses, output contains Provider-native JSON (any
            shape), or null for an empty body.

            - For non-2xx responses, error contains the Provider's error body
            and output is null.


            Sensitive fields are removed from both bodies.
        charge_usd:
          anyOf:
            - type: string
              pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
              description: >-
                Exact USD decimal string (min 2, max 6 decimals, one canonical
                spelling). Sum with decimal arithmetic or scale by 10^6 — never
                floats.
            - type: 'null'
          description: >-
            Historical total Charge of the listed Runs, including replayed or
            read Runs. Null until all listed Runs settle. This is not new
            spending by the current request; request_charge reports that
            separately. Failures can also be charged.
        charge_basis:
          anyOf:
            - type: object
              properties:
                clause:
                  type: string
                  enum:
                    - rule
                    - NO_RESULT
                    - PROVIDER_ERROR
                    - TIMED_OUT
                    - INTERNAL
                quantity:
                  anyOf:
                    - type: integer
                      minimum: 0
                    - type: 'null'
              required:
                - clause
                - quantity
              additionalProperties: false
            - type: 'null'
          description: >-
            Single-Run charge basis, or null for a multi-Run total. Read
            runs[].charge_basis for each charge.
        stoppable:
          type: boolean
          description: >-
            Whether a stop request can currently be accepted. This does not
            guarantee that the Run can stop before dispatch.
        stop_requested_at:
          anyOf:
            - type: string
              description: ISO-8601 UTC timestamp
              format: date-time
            - type: 'null'
          description: >-
            When a stop was requested. The Run can still continue if dispatch
            had already started.
        created_at:
          type: string
          description: ISO-8601 UTC timestamp
          format: date-time
        started_at:
          anyOf:
            - type: string
              description: ISO-8601 UTC timestamp
              format: date-time
            - type: 'null'
        completed_at:
          anyOf:
            - type: string
              description: ISO-8601 UTC timestamp
              format: date-time
            - type: 'null'
        task_id:
          anyOf:
            - type: string
            - type: 'null'
        metadata:
          type: object
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 500
          maxProperties: 20
          propertyNames:
            type: string
            pattern: ^[a-z][a-z0-9_]{0,39}$
          description: >-
            Your stored tracking fields. Use them to filter Runs. They never go
            to the Provider or affect routing, Price, or idempotency.


            - Up to 20 keys: lowercase letters, digits, and underscores; start
            with a letter; at most 40 characters.

            - Values: strings of 1–500 characters.

            - user_id: your End user's opaque ID, never their email address or
            name.
        review_invitation:
          type: object
          properties:
            run_id:
              type: string
            ratings:
              type: array
              items:
                type: string
                enum:
                  - exceeds_expectations
                  - meets_expectations
                  - partially_meets_expectations
                  - does_not_meet_expectations
                  - unable_to_assess
            instruction:
              type: string
          required:
            - run_id
            - ratings
            - instruction
          additionalProperties: false
          description: >-
            Present at most once per Run, on the first delivery of some
            completed Runs. After you use this result for the task, submit a
            review as the instruction says, then continue. Optional; it never
            affects the Run or its charge.
        action:
          type: string
          enum:
            - search
            - product
            - keywords
            - keyword_volume
            - reviews
            - price_history
            - offers
            - merchant_search
            - merchant_page
        result_status:
          type: string
          enum:
            - success
            - no_result
            - error
            - pending
        error:
          anyOf:
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
              required:
                - code
                - message
              additionalProperties: false
            - type: 'null'
        runs:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              run_url:
                type: string
                description: Open this Run in the console. Requires Workspace membership.
              provider:
                type: string
                pattern: ^[a-z0-9][a-z0-9-]*$
              endpoint:
                type: string
                pattern: ^\/.+$
              endpoint_version:
                type: integer
                exclusiveMinimum: 0
              status:
                type: string
                enum:
                  - QUEUED
                  - RUNNING
                  - COMPLETED
                  - FAILED
                  - STOPPED
                description: >-
                  QUEUED or RUNNING: still in progress. COMPLETED: a Provider
                  response is available, including non-2xx responses. FAILED:
                  read failure. STOPPED: stopped before dispatch. Read
                  charge_usd separately from status.
              failure:
                anyOf:
                  - type: object
                    properties:
                      kind:
                        type: string
                        enum:
                          - TIMED_OUT
                          - INTERNAL
                      message:
                        type: string
                    required:
                      - kind
                      - message
                    additionalProperties: false
                  - type: 'null'
                description: Why the Run failed. Non-null only when status is FAILED.
              input:
                type: object
                properties:
                  omitted:
                    type: boolean
                    enum:
                      - true
                required:
                  - omitted
                additionalProperties: false
              output:
                type: object
                properties:
                  omitted:
                    type: boolean
                    enum:
                      - true
                required:
                  - omitted
                additionalProperties: false
              response_file:
                type: object
                properties:
                  body_field:
                    type: string
                    enum:
                      - output
                      - provider_response.error
                  state:
                    type: string
                    enum:
                      - available
                      - link_pending
                      - expired
                      - unavailable
                  download_url:
                    anyOf:
                      - type: string
                      - type: 'null'
                  link_expires_at:
                    anyOf:
                      - type: string
                        description: ISO-8601 UTC timestamp
                        format: date-time
                      - type: 'null'
                  file_expires_at:
                    type: string
                    description: ISO-8601 UTC timestamp
                    format: date-time
                  bytes:
                    type: integer
                    minimum: 0
                  sha256:
                    type: string
                  content_type:
                    type: string
                    enum:
                      - application/json
                required:
                  - body_field
                  - state
                  - download_url
                  - link_expires_at
                  - file_expires_at
                  - bytes
                  - sha256
                  - content_type
                additionalProperties: false
                description: >-
                  Complete large Provider body, delivered as a JSON file.
                  Glasser applies a 32 MiB runtime resource guard to captured
                  bodies and serialized files. body_field identifies the
                  replaced field; output is null or provider_response.error is
                  omitted. Download URLs expire after at most one hour.
                  Authenticated Get Run refreshes the URL while the file is
                  available, for 7 days. Reads and downloads do not execute or
                  charge another Run. If state is link_pending, read the same
                  Run to prepare the link without another execution or charge.
                  The URL grants temporary read access: share it only with
                  intended recipients.
              provider_response:
                anyOf:
                  - type: object
                    properties:
                      http_status:
                        type: integer
                        minimum: 100
                        maximum: 599
                        description: >-
                          HTTP status returned by the Provider. Check this even
                          when the Run is COMPLETED.
                    required:
                      - http_status
                    additionalProperties: false
                  - type: 'null'
              charge_usd:
                anyOf:
                  - type: string
                    pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
                    description: >-
                      Exact USD decimal string (min 2, max 6 decimals, one
                      canonical spelling). Sum with decimal arithmetic or scale
                      by 10^6 — never floats.
                  - type: 'null'
                description: >-
                  Final charge as an exact USD decimal string. Null while QUEUED
                  or RUNNING. A FAILED Run can have a non-zero charge under the
                  Endpoint's Price.
              charge_basis:
                anyOf:
                  - type: object
                    properties:
                      clause:
                        type: string
                        enum:
                          - rule
                          - NO_RESULT
                          - PROVIDER_ERROR
                          - TIMED_OUT
                          - INTERNAL
                      quantity:
                        anyOf:
                          - type: integer
                            minimum: 0
                          - type: 'null'
                    required:
                      - clause
                      - quantity
                    additionalProperties: false
                  - type: 'null'
                description: >-
                  Price clause used to calculate the charge. Null before
                  settlement or when no Provider attempt was made.
              stoppable:
                type: boolean
                description: >-
                  Whether a stop request can currently be accepted. This does
                  not guarantee that the Run can stop before dispatch.
              stop_requested_at:
                anyOf:
                  - type: string
                    description: ISO-8601 UTC timestamp
                    format: date-time
                  - type: 'null'
                description: >-
                  When a stop was requested. The Run can still continue if
                  dispatch had already started.
              created_at:
                type: string
                description: ISO-8601 UTC timestamp
                format: date-time
              started_at:
                anyOf:
                  - type: string
                    description: ISO-8601 UTC timestamp
                    format: date-time
                  - type: 'null'
              completed_at:
                anyOf:
                  - type: string
                    description: ISO-8601 UTC timestamp
                    format: date-time
                  - type: 'null'
              task_id:
                anyOf:
                  - type: string
                  - type: 'null'
              metadata:
                type: object
                additionalProperties:
                  type: string
                  minLength: 1
                  maxLength: 500
                maxProperties: 20
                propertyNames:
                  type: string
                  pattern: ^[a-z][a-z0-9_]{0,39}$
                description: >-
                  Your stored tracking fields. Use them to filter Runs. They
                  never go to the Provider or affect routing, Price, or
                  idempotency.


                  - Up to 20 keys: lowercase letters, digits, and underscores;
                  start with a letter; at most 40 characters.

                  - Values: strings of 1–500 characters.

                  - user_id: your End user's opaque ID, never their email
                  address or name.
            required:
              - id
              - run_url
              - provider
              - endpoint
              - endpoint_version
              - status
              - failure
              - input
              - output
              - provider_response
              - charge_usd
              - charge_basis
              - stoppable
              - stop_requested_at
              - created_at
              - started_at
              - completed_at
              - task_id
              - metadata
            additionalProperties: false
        request_charge:
          type: object
          properties:
            charge_usd:
              anyOf:
                - type: string
                  pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
                  description: >-
                    Exact USD decimal string (min 2, max 6 decimals, one
                    canonical spelling). Sum with decimal arithmetic or scale by
                    10^6 — never floats.
                - type: 'null'
              description: >-
                Charge for Runs created by this request only. Replayed Runs and
                free reads add zero. Null while a newly created Run is unsettled
                or its admission source is unknown. This is not the historical
                total in charge_usd or runs[].charge_usd.
            created_run_ids:
              type: array
              items:
                type: string
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$
                format: uuid
            replayed_run_ids:
              type: array
              items:
                type: string
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$
                format: uuid
            unknown_run_ids:
              type: array
              items:
                type: string
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$
                format: uuid
          required:
            - charge_usd
            - created_run_ids
            - replayed_run_ids
            - unknown_run_ids
          additionalProperties: false
          description: >-
            Request-scoped admission and Charge evidence. Record created_run_ids
            across the user's work, then count each settled Run once. Changing
            task_id does not turn an idempotent replay into a new Run. A result
            read has zero Charge and empty admission lists.
        result_url:
          type: string
          description: >-
            Authenticated, read-only URL path for polling this normalized result
            and total charge. Use with the API origin. Does not create Runs or
            resume fallback. GET /v1/runs/:id still returns the native,
            individual Run.
      required:
        - id
        - run_url
        - provider
        - endpoint
        - endpoint_version
        - status
        - failure
        - input
        - output
        - provider_response
        - charge_usd
        - charge_basis
        - stoppable
        - stop_requested_at
        - created_at
        - started_at
        - completed_at
        - task_id
        - metadata
        - action
        - result_status
        - error
        - runs
        - result_url
      additionalProperties: false
    ValidationFailedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    IdempotencyKeyRequiredEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - idempotency_key_required
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    UnauthorizedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    InsufficientBalanceEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - insufficient_balance
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    EndpointNotPermittedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - endpoint_not_permitted
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    ForbiddenEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - forbidden
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    IdempotencyConflictEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - idempotency_conflict
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    RateLimitedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - rate_limited
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    ServiceUnavailableEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - service_unavailable
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
  securitySchemes:
    bearer:
      type: http
      scheme: Bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.