Plugins

Plugins let you extract structured data from supported platforms (Amazon, Google Search, Google AI Mode, and Google Trends) using the Async API. Instead of sending raw URLs, you specify a plugin key and parameters for each task. The API handles session management, geo-targeting, and response parsing automatically.

Request Structure

POST https://q.scrape.do/api/v1/jobs
X-Token: YOUR_TOKEN
Content-Type: application/json

{
  "Plugin": {
    "Key": "<plugin_key>",
    "Params": [
      { "param1": "value1", "param2": "value2" },
      { "param1": "value3", "param2": "value4" }
    ]
  },
  "WebhookURL": "https://example.com/webhook",
  "WebhookHeaders": { "Authorization": "Bearer your-token" }
}

Targets and Plugin are mutually exclusive. Using both returns 400 Bad Request. Each entry in Params becomes one task in the job. Maximum 1000 params per job.

Supported Plugins

Key	Platform	Output	Description
`amazon/pdp`	Amazon	Structured JSON	Product Detail Page
`amazon/search`	Amazon	Structured JSON	Search results
`amazon/offer-listing`	Amazon	Structured JSON	All seller offers
`google/search`	Google	Structured JSON	SERP results
`google/search/ai-mode`	Google	Structured JSON	AI Mode response
`google/trends`	Google	Structured JSON	Trends data
`walmart/store`	Walmart	Raw HTML	Store-scoped request
`lowes/store`	Lowes	Raw HTML	Store-scoped request

google/search/ai-overview is not available as an async plugin. It requires a session_key from a prior google/search call (90-second TTL) and must be called directly on the gateway.

Amazon Plugins

`amazon/pdp` - Product Detail Page

Returns structured JSON with price, images, rating, buy box, reviews, BSR, and more.

curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "amazon/pdp",
      "Params": [
        { "asin": "B0CQMTCR9T", "zipcode": "32095", "geocode": "us" },
        { "asin": "B0DFK5Y3PQ", "zipcode": "10001", "geocode": "us" }
      ]
    }
  }'

Param	Required	Description
`asin`	yes	Amazon ASIN
`geocode`	yes	Country code (`us`, `gb`, `de`, etc.)
`zipcode`	yes	Zip/postal code
`super`	no	`true` for premium proxies
`include_html`	no	`true` to include raw HTML in response

`amazon/search` - Search Results

curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "amazon/search",
      "Params": [
        { "keyword": "wireless earbuds", "zipcode": "32095", "geocode": "us" },
        { "keyword": "wireless earbuds", "zipcode": "32095", "geocode": "us", "page": 2 }
      ]
    }
  }'

Param	Required	Description
`keyword`	yes	Search query
`geocode`	yes	Country code
`zipcode`	yes	Zip/postal code
`page`	no	Page number (default `1`)
`include_html`	no	`true` to include raw HTML

`amazon/offer-listing` - All Seller Offers

curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "amazon/offer-listing",
      "Params": [
        { "asin": "B0CQMTCR9T", "zipcode": "32095", "geocode": "us" }
      ]
    }
  }'

Google Plugins

All Google plugins return structured JSON and use premium proxies internally. No super flag needed.

`google/search` - SERP Results

curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/search",
      "Params": [
        { "q": "web scraping api", "gl": "us", "hl": "en" },
        { "q": "web scraping api", "gl": "gb", "hl": "en", "start": 10 }
      ]
    }
  }'

Param	Required	Description
`q`	yes	Search query
`gl`	no	Country code (default `us`)
`hl`	no	Language code (default `en`)
`google_domain`	no	Google domain (default `google.com`)
`device`	no	`desktop` or `mobile`
`start`	no	Result offset (default `0`)
`include_html`	no	`true` to include raw HTML

`google/search/ai-mode` - AI Mode

curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/search/ai-mode",
      "Params": [
        { "q": "best web scraping tools 2025", "gl": "us" },
        { "q": "how does web scraping work", "gl": "gb", "hl": "en" }
      ]
    }
  }'

`google/trends` - Trends Data

curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/trends",
      "Params": [
        { "q": "bitcoin", "geo": "US" },
        { "q": "ethereum", "geo": "US", "data_type": "RELATED_QUERIES" }
      ]
    }
  }'

Param	Required	Description
`q`	yes	Search keyword
`geo`	no	Location code (e.g., `US`, `GB`, `US-CA`)
`hl`	no	Language code (default `en`)
`date`	no	Time range (default `today 12-m`)
`data_type`	no	Widget filter: `TIMESERIES`, `GEO_MAP_0`, `RELATED_QUERIES`, `RELATED_TOPICS`
`cat`	no	Category ID
`gprop`	no	Google property: web, `images`, `news`, `youtube`, `froogle`

GeoCode Behavior

GeoCode can be set at two levels:

Level	Example	Applies to
Top-level	`"GeoCode": "us"`	All tasks in the job
Per-param	`{ "geocode": "us", ... }`	That task only

Setting both returns 400. Top-level GeoCode only applies to Amazon, Walmart, and Lowes plugins. Google plugins use per-param gl or geo. Top-level GeoCode has no effect on them.

Webhooks

Plugin jobs support webhooks. Each completed task triggers a webhook delivery:

{
  "Plugin": { "Key": "amazon/pdp", "Params": [...] },
  "WebhookURL": "https://example.com/webhook",
  "WebhookHeaders": { "Authorization": "Bearer your-token" }
}

Error Codes

Status	Message	Cause
`400`	`plugin key is required`	`Plugin.Key` is empty
`400`	`unsupported plugin key: <key>`	Unknown plugin key
`400`	`plugin params are required`	`Plugin.Params` is empty
`400`	`targets cannot be used together with plugin`	Both `Targets` and `Plugin` provided
`400`	`geoCode must not be specified both at top level and in plugin params`	GeoCode conflict
`400`	`plugin params exceed limit of 1000 (got N)`	Too many param entries