finedata-ai Async Scraping API
Submit long-running scrape jobs and retrieve results later. Supports webhooks and batch processing.
Submit long-running scrape jobs and retrieve results later. Supports webhooks and batch processing.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/finedata-ai:finedata-ai-async-scraping-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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