finedata-ai Async Scraping API

openapi: 3.2.0
info:
  title: Finedata Ai Async Scraping API
  version: 1.0.0
  description: 'Operations tagged Async Scraping across 2 of this provider''s published API definitions: finedata-ai.json, finedata-openapi.json. Each path carries the servers of the definition it was published in.'
security:
- BearerAuth: []
tags:
- name: Async Scraping
  description: Submit long-running scrape jobs and retrieve results later. Supports webhooks and batch processing.
paths:
  /api/v1/async/scrape:
    post:
      tags:
      - Async Scraping
      summary: Submit Async Job
      description: 'Submit a scrape job for background processing.


        Returns immediately with a `job_id`. Poll `GET /api/v1/async/jobs/{job_id}` for the result,

        or set `callback_url` to receive a webhook when the job finishes.'
      operationId: create_async_job_api_v1_async_scrape_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AsyncScrapeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/async/jobs/{job_id}:
    get:
      tags:
      - Async Scraping
      summary: Get Job Status
      description: 'Get the current status and result of an async job.


        Statuses: `pending` (queued), `processing` (running), `completed` (result available),

        `failed` (error available), `cancelled`.'
      operationId: get_job_status_api_v1_async_jobs__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Async Scraping
      summary: Cancel Job
      description: 'Cancel a pending job. Only jobs with status `pending` can be cancelled.

        Jobs already `processing` will complete normally.'
      operationId: cancel_job_api_v1_async_jobs__job_id__delete
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/async/jobs:
    get:
      tags:
      - Async Scraping
      summary: List Jobs
      description: List your async jobs, newest first. Supports pagination and status filtering.
      operationId: list_jobs_api_v1_async_jobs_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max jobs to return
          default: 50
          title: Limit
        description: Max jobs to return
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Offset for pagination
          default: 0
          title: Offset
        description: Offset for pagination
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by status: pending, processing, completed, failed, cancelled'
          title: Status
        description: 'Filter by status: pending, processing, completed, failed, cancelled'
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/async/stats:
    get:
      tags:
      - Async Scraping
      summary: Get Job Stats
      description: Get aggregate job counts grouped by status (pending, processing, completed, failed, cancelled).
      operationId: get_job_stats_api_v1_async_stats_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobStatsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/async/batch:
    post:
      tags:
      - Async Scraping
      summary: Submit Batch
      description: Submit up to 100 URLs for parallel async scraping. Returns a `batch_id` to track progress.
      operationId: create_batch_job_api_v1_async_batch_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchScrapeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/async/batch/{batch_id}:
    get:
      tags:
      - Async Scraping
      summary: Get Batch Status
      description: 'Get batch progress. Pass `include_results=true` to get individual job results.


        Statuses: `pending`, `processing`, `completed`, `partial` (some failed), `failed` (all failed).'
      operationId: get_batch_status_api_v1_async_batch__batch_id__get
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          title: Batch Id
      - name: include_results
        in: query
        required: false
        schema:
          type: boolean
          description: Include individual job results
          default: false
          title: Include Results
        description: Include individual job results
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BatchJobStatusResponse:
      properties:
        batch_id:
          type: string
          title: Batch Id
          description: Batch identifier
        status:
          type: string
          title: Status
          description: 'Overall status: pending, processing, completed, partial, failed'
        total_jobs:
          type: integer
          title: Total Jobs
          description: Total jobs in batch
        completed_jobs:
          type: integer
          title: Completed Jobs
          description: Successfully completed jobs
        failed_jobs:
          type: integer
          title: Failed Jobs
          description: Failed jobs
        created_at:
          type: string
          title: Created At
          description: Creation timestamp
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
          description: Completion timestamp (all jobs done)
        results:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Results
          description: Individual job results (when include_results=true)
      type: object
      required:
      - batch_id
      - status
      - total_jobs
      - completed_jobs
      - failed_jobs
      - created_at
      title: BatchJobStatusResponse
      description: Batch progress and results.
    BatchJobResponse:
      properties:
        batch_id:
          type: string
          title: Batch Id
          description: Unique batch identifier
        job_ids:
          items: {}
          type: array
          title: Job Ids
          description: List of individual job IDs
        total_jobs:
          type: integer
          title: Total Jobs
          description: Number of jobs in the batch
        status:
          type: string
          title: Status
          description: Batch status (initially 'pending')
        created_at:
          type: string
          title: Created At
          description: Creation timestamp
      type: object
      required:
      - batch_id
      - job_ids
      - total_jobs
      - status
      - created_at
      title: BatchJobResponse
      description: Returned when a batch is created.
    AsyncJobStatusResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Job identifier
        status:
          type: string
          title: Status
          description: 'Current status: pending, processing, completed, failed, cancelled'
        url:
          type: string
          title: Url
          description: Target URL
        method:
          type: string
          title: Method
          description: HTTP method used
          default: GET
        created_at:
          type: string
          title: Created At
          description: Creation timestamp
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
          description: Processing start timestamp
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
          description: Completion timestamp
        use_js_render:
          type: boolean
          title: Use Js Render
          description: JS rendering was enabled
          default: false
        use_residential:
          type: boolean
          title: Use Residential
          description: Residential proxy was used
          default: false
        use_isp:
          type: boolean
          title: Use Isp
          description: ISP proxy was used
          default: false
        use_mobile:
          type: boolean
          title: Use Mobile
          description: Mobile proxy was used
          default: false
        proxy_country:
          anyOf:
          - type: string
          - type: 'null'
          title: Proxy Country
          description: Requested proxy country (ISO-2), if any
        stealth_antibot:
          type: boolean
          title: Stealth Antibot
          description: Stealth antibot was used
          default: false
        stealth_antibot_headful:
          type: boolean
          title: Stealth Antibot Headful
          description: Headful stealth was used
          default: false
        stealth_new:
          type: boolean
          title: Stealth New
          description: New stealth engine was used
          default: false
        stealth_premium:
          type: boolean
          title: Stealth Premium
          description: Premium stealth engine was used
          default: false
        stealth_premium_headful:
          type: boolean
          title: Stealth Premium Headful
          description: Premium stealth headful was used
          default: false
        result:
          anyOf:
          - type: object
          - type: 'null'
          title: Result
          description: Scrape result (only when status=completed)
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message (only when status=failed)
        attempts:
          type: integer
          title: Attempts
          description: Number of attempts made
          default: 0
        tokens_used:
          type: integer
          title: Tokens Used
          description: Total tokens consumed
          default: 0
      type: object
      required:
      - job_id
      - status
      - url
      - created_at
      title: AsyncJobStatusResponse
      description: Full job status, including result when completed.
    AsyncJobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Unique job identifier (UUID)
        status:
          type: string
          title: Status
          description: Initial job status (always 'pending')
        url:
          type: string
          title: Url
          description: Target URL submitted
        created_at:
          type: string
          title: Created At
          description: ISO 8601 creation timestamp
        estimated_completion:
          anyOf:
          - type: string
          - type: 'null'
          title: Estimated Completion
          description: Estimated completion time (ISO 8601)
      type: object
      required:
      - job_id
      - status
      - url
      - created_at
      title: AsyncJobResponse
      description: Returned when an async job is created.
      example:
        created_at: '2026-02-07T12:00:00Z'
        estimated_completion: '2026-02-07T12:00:30Z'
        job_id: 550e8400-e29b-41d4-a716-446655440000
        status: pending
        url: https://example.com
    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: '#/components/schemas/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
      title: AsyncScrapeRequest
      description: Async scrape request. Same options as sync scrape, plus webhook callback.
      examples:
      - callback_url: https://your-server.com/webhook
        url: https://example.com
        use_js_render: true
      - solve_captcha: true
        stealth_antibot: true
        timeout: 300
        url: https://heavy-site.com
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AsyncJobStatsResponse:
      properties:
        total:
          type: integer
          title: Total
          description: Total jobs
        pending:
          type: integer
          title: Pending
          description: Jobs waiting in queue
        processing:
          type: integer
          title: Processing
          description: Jobs currently running
        completed:
          type: integer
          title: Completed
          description: Successfully completed jobs
        failed:
          type: integer
          title: Failed
          description: Failed jobs
        cancelled:
          type: integer
          title: Cancelled
          description: Cancelled jobs
      type: object
      required:
      - total
      - pending
      - processing
      - completed
      - failed
      - cancelled
      title: AsyncJobStatsResponse
      description: Aggregate job counts by status.
    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
    BatchScrapeRequest:
      properties:
        requests:
          items: {}
          type: array
          maxItems: 100
          minItems: 1
          title: Requests
          description: Array of scrape requests. Each item supports the same fields as AsyncScrapeRequest (without callback_url)
        callback_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Callback Url
          description: Webhook URL called when all jobs in the batch complete
      type: object
      required:
      - requests
      title: BatchScrapeRequest
      description: Submit multiple URLs for async scraping in a single request.
      example:
        callback_url: https://your-server.com/batch-webhook
        requests:
        - url: https://example.com/page1
        - url: https://example.com/page2
          use_js_render: true
        - body: '{}'
          method: POST
          url: https://api.example.com/data
    AsyncJobListResponse:
      properties:
        jobs:
          items: {}
          type: array
          title: Jobs
        total:
          type: integer
          title: Total
          description: Total number of jobs
        limit:
          type: integer
          title: Limit
          description: Page size
        offset:
          type: integer
          title: Offset
          description: Current offset
      type: object
      required:
      - jobs
      - total
      - limit
      - offset
      title: AsyncJobListResponse
      description: Paginated list of async jobs.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API key obtained from the dashboard. Pass as `Authorization: Bearer fd_...`'
x-refined-from:
- finedata-ai.json
- finedata-openapi.json