{
  "openapi": "3.0.1",
  "info": {
    "title": "Target Reviews & Ratings Scraper",
    "description": "Scrape Target.com reviews and ratings by keyword or product URL, and get a rating-distribution summary per product. Search \"laptops\" and every matching product returns its reviews plus star split, sentiment trend and best- and worst-rated attributes.",
    "version": "0.1",
    "x-build-id": "3wYVEDChEEYQ21Nh4"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~target-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-target-reviews-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/blackfalcondata~target-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-target-reviews-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/blackfalcondata~target-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-target-reviews-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "title": "🔍 Search Term",
            "type": "string",
            "description": "Find products by keyword (e.g. \"laptops\") and read their reviews. Use 🛒 Products instead when you already know the exact products. A product URL or TCIN pasted here also works."
          },
          "maxProducts": {
            "title": "🎯 Products Per Search Term",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many products each search term resolves to. Every product costs its own review requests, so this is the main lever on run size. Ignored when you list products directly.",
            "default": 10
          },
          "products": {
            "title": "🛒 Product URLs or TCINs",
            "type": "array",
            "description": "Target.com product URLs or bare TCINs, when you know exactly which products you want. Leave empty to search by keyword instead.",
            "items": {
              "type": "string"
            }
          },
          "maxResults": {
            "title": "💯 Max Reviews",
            "minimum": 0,
            "maximum": 50000,
            "type": "integer",
            "description": "Maximum REVIEW records across all products (0 = as many as Target serves). Target paginates at most 2,550 reviews per product. Product summary records, when enabled, are additional and not counted against this.",
            "default": 100
          },
          "onlyVerified": {
            "title": "✅ Verified Purchases Only",
            "type": "boolean",
            "description": "Only reviews Target marks as a verified purchase.",
            "default": false
          },
          "onlyWithPhotos": {
            "title": "📷 Reviews With Photos Only",
            "type": "boolean",
            "description": "Only reviews that include customer photos.",
            "default": false
          },
          "minRating": {
            "title": "⭐ Minimum Star Rating",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Drop reviews below this rating (1–5). Leave empty for all ratings. Ratings-only records (products with stars but no written review) are always kept."
          },
          "sortBy": {
            "title": "🔀 Sort Reviews",
            "enum": [
              "source",
              "most_recent",
              "oldest",
              "highest_rating",
              "lowest_rating",
              "most_helpful"
            ],
            "type": "string",
            "description": "Order of the delivered reviews. Target ignores sort requests, so this is applied to the reviews this run collected: with a Max Reviews cap the run reads the first N in Target's own order and sorts those. To rank across every review of a product, set Max Reviews to 0.",
            "default": "source"
          },
          "includeDetails": {
            "title": "📋 Include Product Details",
            "type": "boolean",
            "description": "Add the product title, brand, image and category to every review. Costs one extra request per product, not per review.",
            "default": true
          },
          "includeProductSummary": {
            "title": "📊 Product Rating Summary",
            "type": "boolean",
            "description": "Add one analysis record per product: the star distribution as percentages, positive/negative split, verified and photo shares, review counts per year, a 12-month rating trend, the best- and worst-rated attributes, and the most helpful review. Computed from the reviews the run already fetched — no extra requests. Adds one record per product to the results.",
            "default": true
          },
          "descriptionMaxLength": {
            "title": "✂️ Review Text Max Length",
            "minimum": 0,
            "type": "integer",
            "description": "Truncate the review body to N characters. 0 = no truncation.",
            "default": 0
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Core fields only (for AI-agent/MCP workflows).",
            "default": false
          },
          "descriptionFormat": {
            "title": "📝 Review Text Format",
            "enum": [
              "all",
              "text",
              "html",
              "markdown"
            ],
            "type": "string",
            "description": "Which representations of the review body to emit. `all` keeps text + descriptionText + descriptionHtml + descriptionMarkdown. `text` / `html` / `markdown` keep only one variant.",
            "default": "all"
          },
          "excludeEmptyFields": {
            "title": "🧹 Exclude Empty Fields",
            "type": "boolean",
            "description": "Drop null / empty-string / empty-array fields from each output record. Off by default to preserve dataset schema compatibility; turn on to slim output for LLM / agent consumption.",
            "default": false
          },
          "incrementalMode": {
            "title": "♻️ Incremental Mode",
            "type": "boolean",
            "description": "Compare against the previous run and emit only new or changed reviews. Leave State Key empty and each product set is tracked separately.",
            "default": false
          },
          "stateKey": {
            "title": "🔑 State Key",
            "type": "string",
            "description": "Optional. Stable identifier for the tracked product set. Leave empty to auto-generate from the product list."
          },
          "emitUnchanged": {
            "title": "♻️ Emit Unchanged",
            "type": "boolean",
            "description": "Also emit reviews that have not changed since the last run (incrementalMode only).",
            "default": false
          },
          "emitExpired": {
            "title": "⚰️ Emit Removed Reviews",
            "type": "boolean",
            "description": "Also emit reviews that have disappeared since the last run — deleted or moderated away (incrementalMode only). Suppressed automatically when a filter or Target's own pagination window means the run did not see every review of a product.",
            "default": false
          },
          "telegramToken": {
            "title": "🔑 Telegram Bot Token",
            "type": "string",
            "description": "Telegram bot token (from @BotFather). Required for Telegram notifications."
          },
          "telegramChatId": {
            "title": "💬 Telegram Chat ID",
            "type": "string",
            "description": "Telegram chat or channel ID (e.g. \"-100123456789\"). Required when telegramToken is set."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord incoming webhook URL. Server Settings → Integrations → Webhooks → New Webhook."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL. api.slack.com/messaging/webhooks."
          },
          "notificationLimit": {
            "title": "📊 Max Reviews Per Notification",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of reviews included in each notification message (1–20).",
            "default": 5
          },
          "notifyOnlyChanges": {
            "title": "🔄 Notify Only New/Updated",
            "type": "boolean",
            "description": "When Incremental Mode is on, only send notifications for NEW and UPDATED reviews. Has no effect outside incremental mode.",
            "default": false
          },
          "whatsappAccessToken": {
            "title": "📱 WhatsApp Access Token",
            "type": "string",
            "description": "WhatsApp Cloud API permanent access token (System User token from Meta Business). Recipient must have messaged the business number within the last 24h."
          },
          "whatsappPhoneNumberId": {
            "title": "📞 WhatsApp Phone Number ID",
            "type": "string",
            "description": "Your WhatsApp Business phone-number ID (numeric, from Meta dashboard). Required when whatsappAccessToken is set."
          },
          "whatsappTo": {
            "title": "📲 WhatsApp Recipient",
            "type": "string",
            "description": "Recipient phone in E.164 format without + (e.g. \"436641234567\")."
          },
          "webhookUrl": {
            "title": "🪝 Generic Webhook URL",
            "type": "string",
            "description": "Receives a JSON POST with {metadata, items} after each run. Universal escape hatch for n8n / Make / Zapier / custom backends."
          },
          "webhookHeaders": {
            "title": "📋 Webhook Headers",
            "type": "object",
            "description": "Optional JSON object of custom headers (e.g. {\"Authorization\":\"Bearer ...\"})."
          },
          "appConnector": {
            "title": "Send results to a connected app",
            "type": "string",
            "description": "Optional. Pick a connected app under Settings → API & Integrations to receive your results. Best-effort across MCP connectors as Apify expands its catalog."
          },
          "mcpIssueTeam": {
            "title": "Issue tracker team",
            "type": "string",
            "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}