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

# Read an Amazon research result

> Read normalized output, delivery status and total charges for the same Amazon research Runs.

Follow result\_url unchanged with authentication. This read creates no Run, calls no Provider and does not resume fallback. HTTP 200 can still contain result\_status=pending. The signed context is bound to the Workspace; each Run is checked against the current Key policy.


## OpenAPI

````yaml /openapi.json get /v1/solutions/gtm/amazon_research/result
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/result:
    get:
      tags:
        - Solutions
      summary: Read an Amazon research result
      description: >-
        Follow result_url from an Amazon research call to read normalized
        output, business result_status and the total charge of the same Runs.
        HTTP 200 may still contain result_status=pending. This authenticated
        read creates no Runs, calls no Providers and does not resume fallback.
        GET /v1/runs/:id remains the native individual Run. The result context
        is signed, bound to the Workspace and checked against the current Key
        policy for every Run.
      operationId: gtm-amazon-research-result
      parameters:
        - name: token
          in: query
          schema:
            type: string
            minLength: 1
            maxLength: 16384
            description: >-
              Opaque result context returned in result_url. Keep it unchanged
              and authenticate with a Key permitted to read every listed Run.
          required: true
      responses:
        '200':
          description: AmazonResearchResult
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonResearchResult'
        '400':
          description: ValidationFailed
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedEncoded'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenEncoded'
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundEncoded'
        '429':
          description: RateLimited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedEncoded'
      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
    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
    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
    NotFoundEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - not_found
            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
  securitySchemes:
    bearer:
      type: http
      scheme: Bearer

````

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