AsyncScrapeRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/finedata-ai/json-schema/finedata-ai-async-scrape-request-schema.json",
  "title": "AsyncScrapeRequest",
  "description": "Async scrape request. Same options as sync scrape, plus webhook callback.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/finedata-openapi.json#/components/schemas/AsyncScrapeRequest",
  "properties": {
    "url": {
      "type": "string",
      "title": "Url",
      "description": "Target URL to scrape"
    },
    "method": {
      "type": "string",
      "title": "Method",
      "description": "HTTP method (GET, POST, PUT, DELETE)",
      "default": "GET"
    },
    "headers": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Headers",
      "description": "Custom HTTP headers"
    },
    "body": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Body",
      "description": "Request body (for POST/PUT)"
    },
    "tls_profile": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tls Profile",
      "description": "TLS fingerprint profile: chrome145, chrome136, firefox147, safari26_0, smart, vip",
      "default": "chrome136"
    },
    "max_retries": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 10.0,
          "minimum": 1.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Max Retries",
      "description": "Max retry attempts",
      "default": 5
    },
    "timeout": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 300.0,
          "minimum": 5.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Timeout",
      "description": "Timeout in seconds (max 300 for captcha)",
      "default": 120
    },
    "use_antibot": {
      "type": "boolean",
      "title": "Use Antibot",
      "description": "Browser-like TLS fingerprint (+2 tokens)",
      "default": true
    },
    "use_js_render": {
      "type": "boolean",
      "title": "Use Js Render",
      "description": "Render JavaScript with headless browser (+5 tokens)",
      "default": false
    },
    "use_residential": {
      "type": "boolean",
      "title": "Use Residential",
      "description": "Residential proxy (+3 tokens)",
      "default": false
    },
    "use_isp": {
      "type": "boolean",
      "title": "Use Isp",
      "description": "ISP proxy (+2 tokens)",
      "default": false
    },
    "use_mobile": {
      "type": "boolean",
      "title": "Use Mobile",
      "description": "Mobile carrier proxy (+4 tokens)",
      "default": false
    },
    "proxy_sticky": {
      "type": "boolean",
      "title": "Proxy Sticky",
      "description": "Keep the same proxy exit IP across requests in this job. Works with residential and BYOP sticky profiles.",
      "default": false
    },
    "proxy_country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Proxy Country",
      "description": "Request a proxy exit IP from a specific country (ISO-2 code, e.g. 'US', 'DE'). Applies to datacenter, residential, ISP and mobile proxies. Mutually exclusive with proxy_profile_id (BYOP)."
    },
    "proxy_profile_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Proxy Profile Id",
      "description": "Use your own proxy list via a saved BYOP profile id. Mutually exclusive with use_residential/use_isp/use_mobile. Charges flat +1 token. Requires team_s plan or admin override."
    },
    "stealth_antibot": {
      "type": "boolean",
      "title": "Stealth Antibot",
      "description": "Stronger browser emulation for pages a plain request cannot load (+7 tokens)",
      "default": false
    },
    "stealth_antibot_headful": {
      "type": "boolean",
      "title": "Stealth Antibot Headful",
      "description": "Full real browser with a visible display (+25 tokens)",
      "default": false
    },
    "stealth_new": {
      "type": "boolean",
      "title": "Stealth New",
      "description": "Experimental next-gen engine (+15 tokens)",
      "default": false
    },
    "stealth_premium": {
      "type": "boolean",
      "title": "Stealth Premium",
      "description": "Premium stealth engine (+20 tokens)",
      "default": false
    },
    "stealth_premium_headful": {
      "type": "boolean",
      "title": "Stealth Premium Headful",
      "description": "Premium stealth headful mode (+30 tokens)",
      "default": false
    },
    "js_wait_for": {
      "type": "string",
      "title": "Js Wait For",
      "description": "Page load strategy: networkidle, load, domcontentloaded, or selector:.css",
      "default": "networkidle"
    },
    "js_scroll": {
      "type": "boolean",
      "title": "Js Scroll",
      "description": "Scroll to load lazy content",
      "default": false
    },
    "js_actions": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/JsAction"
          },
          "type": "array",
          "maxItems": 10
        },
        {
          "type": "null"
        }
      ],
      "title": "Js Actions",
      "description": "Browser actions before extraction: click, wait, type, scroll, hover, evaluate (+2 tokens each, max 10)"
    },
    "solve_captcha": {
      "type": "boolean",
      "title": "Solve Captcha",
      "description": "Auto-solve captchas: reCAPTCHA, hCaptcha, Turnstile (+10 tokens)",
      "default": false
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Session Id",
      "description": "Sticky session ID for same proxy IP across requests"
    },
    "session_ttl": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 86400.0,
          "minimum": 60.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Session Ttl",
      "description": "Session lifetime in seconds (default 1800)",
      "default": 1800
    },
    "formats": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Formats",
      "description": "Output formats to include in response. Options: 'markdown', 'rawHtml', 'text', 'links', 'screenshot'. If not specified, only 'body' (raw HTML) is returned for backward compatibility. Example: ['markdown', 'links']"
    },
    "only_main_content": {
      "type": "boolean",
      "title": "Only Main Content",
      "description": "Extract only the main content of the page (removes navigation, footer, sidebar, ads). Applies to 'markdown' and 'text' formats. Uses Mozilla Readability algorithm",
      "default": false
    },
    "extract_rules": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Extract Rules",
      "description": "CSS/XPath selectors for structured data extraction. Simple: {'title': 'h1', 'price': '.price'}. Advanced: {'links': {'selector': 'a.product', 'type': 'list', 'output': '@href'}}. Supported types: text (default), html, list. Output: text content or @attr"
    },
    "extract_schema": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Extract Schema",
      "description": "JSON Schema for AI-powered structured data extraction. The AI model analyzes page content and returns data matching your schema. Example: {'type': 'object', 'properties': {'products': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': 'string'}, 'price': {'type': 'number'}}}}}} (+5 tokens)"
    },
    "extract_prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Extract Prompt",
      "description": "Natural language instruction for AI-powered data extraction. Alternative to extract_schema. Example: 'Extract all product names, prices, and ratings from this page' (+5 tokens)"
    },
    "ai_content_mode": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "full",
            "main"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Ai Content Mode",
      "description": "Content mode for AI extraction (extract_schema/extract_prompt). 'full' — AI sees full page content including sidebars, structured data blocks (best for product pages, real estate listings, marketplaces). 'main' — AI sees only main content extracted via Readability algorithm (best for articles, blog posts — fewer tokens, less noise). Default: 'full'",
      "default": "full"
    },
    "callback_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Callback Url",
      "description": "Webhook URL to receive the result when job completes"
    },
    "callback_headers": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Callback Headers",
      "description": "Custom headers sent with the webhook POST"
    }
  },
  "type": "object",
  "required": [
    "url"
  ],
  "$defs": {
    "JsAction": {
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "click",
            "wait",
            "wait_for",
            "scroll",
            "type",
            "hover",
            "screenshot",
            "evaluate"
          ],
          "title": "Action",
          "description": "Action type: click, wait, wait_for, scroll, type, hover, screenshot, evaluate"
        },
        "selector": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Selector",
          "description": "CSS selector for the target element"
        },
        "ms": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 30000.0,
              "minimum": 100.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Ms",
          "description": "Wait time in milliseconds (for 'wait' action). Accepts both 'ms' and 'value' keys"
        },
        "text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Text",
          "description": "Text to type (for 'type' action)"
        },
        "timeout": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 30000.0,
              "minimum": 1000.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Timeout",
          "description": "Timeout for wait_for in ms",
          "default": 10000
        },
        "y": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Y",
          "description": "Y position for scroll (if no selector)"
        },
        "script": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 10000
            },
            {
              "type": "null"
            }
          ],
          "title": "Script",
          "description": "JavaScript code to execute on the page (for 'evaluate' action). Runs in the page context with a 15s timeout. Max 10,000 characters"
        }
      },
      "type": "object",
      "required": [
        "action"
      ],
      "title": "JsAction",
      "description": "JavaScript action to perform on page"
    }
  }
}