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

# Amazon Rufus

> Extract structured product recommendations from Amazon Rufus - ASINs, ratings, editorial tags, and follow-up questions - as clean JSON.

<Info>
  **Structured product cards with ASINs**

  Every product recommendation includes an ASIN - Amazon's unique product identifier - making it easy to cross-reference products, track recommendation changes over time, and link directly to product listings.
</Info>

## Overview

Use this endpoint to monitor which products Amazon's AI recommends for any category, track competitor product placements in Rufus answers, and research what editorial tags (like "Best overall" or "Best value") Amazon assigns to products in your space.

## Unique features

* **ASINs**: Amazon Standard Identification Numbers for every recommended product - enabling direct product tracking
* **Editorial tags**: Rufus's curated labels like "Best overall", "Best value", or "Most reviewed"
* **Related questions**: Follow-up questions Rufus suggests - useful for understanding shopping intent
* **Multi-marketplace**: Automatic routing to the correct Amazon marketplace based on country code

## Supported marketplaces

| Country code | Marketplace   |
| ------------ | ------------- |
| `US`         | amazon.com    |
| `GB`         | amazon.co.uk  |
| `DE`         | amazon.de     |
| `FR`         | amazon.fr     |
| `IT`         | amazon.it     |
| `ES`         | amazon.es     |
| `CA`         | amazon.ca     |
| `AU`         | amazon.com.au |
| `JP`         | amazon.co.jp  |
| `IN`         | amazon.in     |

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  # Streaming can take up to 300s - --max-time matches the server timeout
  curl --max-time 300 \
    -G "https://api.scrapellm.com/scrapers/amazon-rufus" \
    --data-urlencode "api_key=YOUR_API_KEY" \
    --data-urlencode "prompt=What are the best wireless headphones for working from home?" \
    --data-urlencode "country=US"
  ```

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

  response = requests.get(
      "https://api.scrapellm.com/scrapers/amazon-rufus",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={
          "prompt": "What are the best wireless headphones for working from home?",
          "country": "US",
      }
  )
  data = response.json()
  for product in data["products"]:
      print(f"{product['asin']}  {product['rating']}★  {product['title'][:80]}")
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    prompt: "What are the best wireless headphones for working from home?",
    country: "US",
  });

  const response = await fetch(
    `https://api.scrapellm.com/scrapers/amazon-rufus?${params}`,
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const data = await response.json();
  for (const product of data.products) {
    console.log(`${product.asin}  ${product.rating}★  ${product.title.slice(0, 80)}`);
  }
  ```
</CodeGroup>

## Response schema

Includes [common response fields](/guides/making-requests#common-response-fields) plus:

| Field                  | Type    | Description                                                                    |
| ---------------------- | ------- | ------------------------------------------------------------------------------ |
| `result`               | string  | Rufus's plain-text answer to the query                                         |
| `products`             | array   | Structured product recommendations                                             |
| `products[].asin`      | string  | Amazon Standard Identification Number                                          |
| `products[].title`     | string  | Product title as shown in Rufus                                                |
| `products[].rating`    | string  | Customer rating (e.g. `"4.5"`). Nullable                                       |
| `products[].reviews`   | string  | Number of customer reviews (e.g. `"18,423"`). Nullable                         |
| `products[].image_url` | string  | Product image URL. Nullable                                                    |
| `products[].category`  | string  | Product category label. Nullable                                               |
| `products[].url`       | string  | Absolute URL to the Amazon product listing. Nullable                           |
| `products[].footer`    | string  | Rufus editorial tag (e.g. `"Best overall"`, `"Best value"`). Nullable          |
| `related_questions`    | array   | Follow-up questions Rufus suggests for further shopping research               |
| `interim_messages`     | array   | Loading-state messages localised to the marketplace (e.g. "Checking reviews…") |
| `credits_used`         | integer | Credits consumed - always `4` for Amazon Rufus                                 |
| `elapsed_ms`           | float   | End-to-end request duration in milliseconds                                    |
| `cached`               | boolean | `true` if served from cache                                                    |

## Common questions

### Why does Amazon Rufus cost 4 credits instead of 3?

Rufus requires authenticated Amazon sessions with anti-bot token handling and real-time SSE stream parsing - more infrastructure than a standard web scrape. The extra credit reflects this complexity.

### Are all product fields always populated?

No. Fields like `rating`, `reviews`, `image_url`, `category`, `url`, and `footer` are nullable - Rufus doesn't always return all fields for every product. Always check for null before processing.

### How do I track if my product appears in Rufus recommendations?

Query your product category and check `products[].asin` for your ASIN. Run the same prompt repeatedly across different countries to monitor regional placement and track changes over time.

### Which marketplaces support all features?

All supported marketplaces return ASINs, titles, and follow-up questions. Rating, review count, and editorial tags depend on the marketplace's Rufus implementation and may vary by region.


## OpenAPI

````yaml GET /scrapers/amazon_rufus
openapi: 3.1.0
info:
  title: ScrapeLLM — Amazon Rufus Scraper
  version: 1.0.0
  description: >
    Scrape Amazon Rufus — Amazon's conversational shopping assistant — via
    ScrapeLLM.

    Returns curated product recommendations and follow-up questions as
    structured JSON.

    Authentication, SSE parsing, anti-bot tokens, and marketplace routing are
    all

    handled server-side.


    **Base URL:** `https://api.scrapellm.com`


    **Credits:** 3 per request · 1500 free credits · No credit card required


    Get your API key at [scrapellm.com/signup](https://scrapellm.com/signup).
  contact:
    email: hello@scrapellm.com
    url: https://scrapellm.com
  license:
    name: ScrapeLLM Terms of Service
    url: https://scrapellm.com/terms
servers:
  - url: https://api.scrapellm.com
    description: Production
security:
  - ApiKeyHeader: []
  - ApiKeyQuery: []
tags:
  - name: Amazon Rufus Scraper
    description: >-
      Submit shopping queries to Amazon Rufus and receive structured product
      recommendations.
paths:
  /scrapers/amazon_rufus:
    get:
      tags:
        - Amazon Rufus Scraper
      summary: Send an Amazon Rufus Scraping Request
      description: >
        Send a shopping query to Amazon Rufus via an authenticated Amazon
        session and get

        structured product recommendations and follow-up questions as JSON.


        Blocks until Rufus responds or `timeout` is reached.


        **Authentication** — pass your API key via the `X-API-Key` header or as
        `?api_key=`

        in the URL.
      operationId: scrapeAmazonRufus
      parameters:
        - name: prompt
          in: query
          required: true
          description: >
            The shopping query to send to Amazon Rufus. Free-form natural
            language:

            direct questions, product comparisons, or shopping intent.

            Maximum 4,000 characters.
          schema:
            type: string
            minLength: 1
            maxLength: 4000
          example: best wireless headphones under $100
        - name: country
          in: query
          required: false
          description: >
            ISO 3166-1 alpha-2 country code for the Amazon marketplace.

            Maps to the appropriate domain: `US` → amazon.com, `GB` →
            amazon.co.uk,

            `DE` → amazon.de, `ES` → amazon.es, etc. Defaults to `US`.
          schema:
            type: string
            minLength: 2
            maxLength: 2
            default: US
          example: US
        - name: bypass_cache
          in: query
          required: false
          description: Skip the response cache and always fetch a fresh result.
          schema:
            type: boolean
            default: false
        - name: timeout
          in: query
          required: false
          description: >-
            Maximum seconds to wait for Rufus to respond. Must be between 10 and
            600.
          schema:
            type: number
            format: float
            minimum: 10
            maximum: 600
            default: 300
      responses:
        '200':
          description: Scrape completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonRufusScrapeResponse'
              example:
                scraper: amazon_rufus
                status: done
                job_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                prompt: best wireless headphones under $100
                country: US
                products:
                  - asin: B09XYZ1234
                    title: Sony WH-CH520 Wireless Headphones
                    rating: '4.5'
                    reviews: 18,423
                    image_url: https://m.media-amazon.com/images/I/example.jpg
                    image_alt: Sony WH-CH520 Wireless Headphones
                    category: Electronics
                    url: https://www.amazon.com/dp/B09XYZ1234
                    footer: Best overall
                related_questions:
                  - What headphones have the best noise cancellation?
                  - Sony vs Bose wireless headphones comparison
                interim_messages:
                  - Checking reviews...
                  - Gathering data...
                credits_used: 3
                elapsed_ms: 8341.2
                cached: false
                markdown_url: >-
                  https://scrapellm.com/md/3fa85f64-5717-4562-b3fc-2c963f66afa6.md
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Missing API key. Pass your key in the X-API-Key header or as
                  ?api_key= in the URL.
        '429':
          description: Credit limit reached or scraper queue is full — retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >-
            Rufus returned an empty result or an unexpected error — safe to
            retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Scraper pool is still warming up — retry in a few seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Network timeout reaching the scraper machine.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: >
            # Streaming can take up to 300s - --max-time matches the server
            timeout

            curl --max-time 300 \
              -G "https://api.scrapellm.com/scrapers/amazon_rufus" \
              --data-urlencode "api_key=YOUR_API_KEY" \
              --data-urlencode "prompt=What are the best wireless headphones for working from home?" \
              --data-urlencode "country=US"
        - lang: Python
          label: Python
          source: |
            import requests

            response = requests.get(
                "https://api.scrapellm.com/scrapers/amazon_rufus",
                params={
                    "api_key": "YOUR_API_KEY",
                    "prompt": "What are the best wireless headphones for working from home?",
                    "country": "US",
                }
            )
            print(response.json())
        - lang: JavaScript
          label: JavaScript
          source: |
            const params = new URLSearchParams({
              api_key: "YOUR_API_KEY",
              prompt: "What are the best wireless headphones for working from home?",
              country: "US",
            });

            const response = await fetch(
              `https://api.scrapellm.com/scrapers/amazon_rufus?${params}`
            );
            const data = await response.json();
            console.log(data);
        - lang: TypeScript
          label: TypeScript
          source: |
            const params = new URLSearchParams({
              api_key: "YOUR_API_KEY",
              prompt: "What are the best wireless headphones for working from home?",
              country: "US",
            });

            const response = await fetch(
              `https://api.scrapellm.com/scrapers/amazon_rufus?${params}`
            );
            const data = await response.json();
            console.log(data);
components:
  schemas:
    AmazonRufusScrapeResponse:
      type: object
      required:
        - scraper
        - status
        - job_id
        - prompt
        - country
        - products
        - related_questions
        - credits_used
        - elapsed_ms
        - cached
      properties:
        scraper:
          type: string
          description: Always `"amazon_rufus"`.
          example: amazon_rufus
        status:
          type: string
          description: '`"done"` on success.'
          example: done
        job_id:
          type: string
          description: Unique identifier for this scrape job.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        prompt:
          type: string
          description: The shopping query that was submitted.
          example: best wireless headphones under $100
        country:
          type: string
          description: The Amazon marketplace country targeted.
          example: US
        products:
          type: array
          description: |
            Rufus's curated product list for the query. Typically 3–6 items.
            Empty array if Rufus found no recommendations.
          items:
            $ref: '#/components/schemas/AmazonRufusProduct'
        related_questions:
          type: array
          description: |
            Follow-up shopping questions generated by Rufus.
            Useful for query expansion, SEO keyword research, or chained calls.
          items:
            type: string
          example:
            - What headphones have the best noise cancellation?
            - Sony vs Bose wireless headphones comparison
        interim_messages:
          type: array
          description: Loading-state messages localised to the marketplace.
          items:
            type: string
          example:
            - Checking reviews...
        credits_used:
          type: integer
          description: Credits consumed by this request. Always `3`.
          example: 3
        elapsed_ms:
          type: number
          format: float
          description: Total end-to-end request duration in milliseconds.
          example: 8341.2
        cached:
          type: boolean
          description: '`true` if this response was served from cache.'
          example: false
        markdown_url:
          type: string
          nullable: true
          description: |
            Hosted `.md` summary URL for this response. Expires after 24 hours.
          example: https://scrapellm.com/md/3fa85f64-5717-4562-b3fc-2c963f66afa6.md
        api_version:
          type: string
          description: API version that produced this response.
          example: 1.0.0
        created_at:
          type: string
          nullable: true
          description: ISO 8601 UTC timestamp when the gateway processed this response.
          example: '2026-05-27T12:00:00+00:00'
        cached_at:
          type: string
          nullable: true
          description: |
            ISO 8601 UTC timestamp when this response was originally cached.
            Only present when `cached` is `true`.
          example: '2026-05-27T12:00:00+00:00'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable description of the error.
          example: Invalid API key.
    AmazonRufusProduct:
      type: object
      required:
        - asin
        - title
      properties:
        asin:
          type: string
          description: Amazon Standard Identification Number.
          example: B09XYZ1234
        title:
          type: string
          description: Product title as shown in Rufus.
          example: Sony WH-CH520 Wireless Headphones
        rating:
          type: string
          nullable: true
          description: Customer rating as a string (e.g. "4.5").
          example: '4.5'
        reviews:
          type: string
          nullable: true
          description: Number of customer reviews (may include comma formatting).
          example: 18,423
        image_url:
          type: string
          nullable: true
          description: Product image URL.
          example: https://m.media-amazon.com/images/I/example.jpg
        image_alt:
          type: string
          nullable: true
          description: Alt text for the product image.
        category:
          type: string
          nullable: true
          description: Product category label.
          example: Electronics
        url:
          type: string
          nullable: true
          format: uri
          description: Absolute URL to the Amazon product listing.
          example: https://www.amazon.com/dp/B09XYZ1234
        footer:
          type: string
          nullable: true
          description: Rufus editorial tag (e.g. "Best overall", "Best value").
          example: Best overall
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your ScrapeLLM API key passed in the request header.
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Your ScrapeLLM API key passed as a query parameter.

````