API Documentation

Quick Start

Create an account, copy your API key from the dashboard, and replace fd_your_api_key below. This request reads a public page and returns markdown.

curl -X POST https://api.finedata.ai/api/v1/scrape \
  -H "Content-Type: application/json" \
  -H "x-api-key: fd_your_api_key" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}'

import requests

resp = requests.post(
    "https://api.finedata.ai/api/v1/scrape",
    headers={"x-api-key": "fd_your_api_key"},
    json={"url": "https://example.com", "formats": ["markdown"]},
    timeout=130,
)
resp.raise_for_status()
data = resp.json()
if data["success"] is False:
    raise RuntimeError(data)
print(data["data"]["markdown"])

const resp = await fetch("https://api.finedata.ai/api/v1/scrape", {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": "fd_your_api_key" },
  body: JSON.stringify({ url: "https://example.com", formats: ["markdown"] })
});
if (resp.ok === false) throw new Error(await resp.text());
const data = await resp.json();
if (data.success === false) throw new Error(JSON.stringify(data));
console.log(data.data.markdown);

Authentication

All requests require one of:

curl -X POST https://api.finedata.ai/api/v1/scrape \
  -H "x-api-key: fd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","formats":["markdown"]}'

curl -X POST https://api.finedata.ai/api/v1/scrape \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","formats":["markdown"]}'

Token Pricing

Tokens are API usage credits, not LLM input tokens. A default request uses 3: 1 base + 2 for TLS fingerprinting. Failed scrapes are not billed. Add one rendering mode and any routing, extraction or action costs you need.

Scrape Endpoint

Send a JSON body with a target URL. Add only the options your page needs.

{
  "url": "https://example.com",
  "formats": ["markdown"],
  "only_main_content": true
}

For every field and constraint, use the interactive reference or OpenAPI schema.

Response

Illustrative response, shortened for readability. Only requested output fields are populated.

{
  "success": true,
  "status_code": 200,
  "body": "<html>...</html>",
  "data": {
    "markdown": "# Example Domain\n\nThis domain is for use..."
  },
  "meta": {"url": "https://example.com", "elapsed_ms": 1250},
  "tokens_used": 3
}

Check the API HTTP status first, then success. The JSON field status_code is the target page's status, not the API's. Read content from data.markdown and actual usage from tokens_used.

Google SERP

Run a Google search server-side and get the results as JSON. It uses the same API-key authentication as /api/v1/scrape. The API builds the Google URL from your query, so you never send a target URL. Use it to monitor the ranking and visibility of your own domains and brand queries. Follow the Acceptable Use Policy: the permitted case is SEO and SERP tracking for your own domains.

curl -X POST https://api.finedata.ai/api/v1/serp \
  -H "Content-Type: application/json" \
  -H "x-api-key: fd_your_api_key" \
  -d '{"q": "rank tracking tool", "gl": "us", "hl": "en", "start": 0}'

Response

Illustrative response, shortened for readability. Blocks such as ads, answer_box, knowledge_graph, top_stories, local_results, people_also_ask, related_searches, shopping_results and video_results appear only when the page carries them.

{
  "search_metadata": {
    "id": "3f6c1e9a-…",
    "status": "ok",
    "created_at": "2026-10-13T12:00:00+00:00",
    "processing_time_ms": 1840,
    "google_url": "<google search url built from q, gl, hl, start>"
  },
  "search_information": {
    "query_displayed": "rank tracking tool",
    "total_results": 412000000
  },
  "organic_results": [
    {
      "position": 1,
      "title": "Rank Tracking Tool — Example",
      "link": "https://example.com/rank-tracker",
      "displayed_link": "example.com › rank-tracker",
      "snippet": "Track keyword positions for your own domains…",
      "sitelinks": [
        {"title": "Pricing", "link": "https://example.com/pricing"}
      ]
    }
  ],
  "tokens_charged": 10
}

Each request costs a flat 10 tokens, reported as tokens_charged; gl, hl and start do not change the price. Links resolve away from Google's redirect wrapper, so organic_results[].link is the destination URL. A blocked or unparseable Google page costs nothing.

Over MCP the same search is the google_search tool with arguments q, gl, hl and start; it needs the scrape:write scope. See MCP Integration.

Output Formats

Use the formats array to control what appears in data.

Content without the wrapper

REST returns raw HTML in body if you omit formats. Request a format explicitly. For content-only output, add raw_output: true with exactly one format.

{
  "url": "https://example.com",
  "formats": ["markdown"],
  "raw_output": true
}

The response is markdown, not JSON. Metadata moves to X-Tokens-Used, X-Request-Id and X-Status-Code headers. CSV/XLSX require extract_prompt or extract_schema; use the synchronous endpoint for these exports.

AI Extraction

Extract with CSS/XPath selectors (no extra extraction fee) or AI (+5 tokens). AI-only results are in data.extract; when combined with selector results, AI data is nested under data.extract.ai_extract. These product URLs and selectors are illustrative.

{
  "url": "https://example.com/product",
  "extract_rules": {
    "title": "h1",
    "price": ".product-price",
    "images": {"selector": "img.product-image", "type": "list", "output": "@src"}
  }
}

{
  "url": "https://example.com/product",
  "formats": ["markdown"],
  "extract_prompt": "Extract product name, price, rating, and availability"
}

{
  "url": "https://example.com/product",
  "extract_schema": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "price": {"type": "number"},
      "in_stock": {"type": "boolean"}
    }
  }
}

Render, wait, then extract

For JavaScript pages, wait for the content you need rather than adding an arbitrary delay. This illustrative sequence expands a product description before extraction; replace the URL and selectors with your page's.

{
  "url": "https://example.com/product",
  "use_js_render": true,
  "js_wait_for": "selector:.product",
  "js_actions": [
    {"action": "click", "selector": ".expand-description"},
    {"action": "wait_for", "selector": ".description-expanded"}
  ],
  "extract_prompt": "Extract the product name and full description"
}

Up to 10 actions: click, wait, wait_for, scroll, type, hover, screenshot, evaluate. Browser interactions can change the target site: use only actions you are authorized to perform.

Async & Batch Scraping

Background processing for large-scale scraping or slow pages.

{
  "url": "https://example.com",
  "formats": ["markdown"]
}

Submit a batch and collect results

POST this body to /api/v1/async/batch. REST uses requests, an array of request objects; the MCP batch_scrape tool uses urls instead.

{
  "requests": [
    {"url": "https://example.com", "formats": ["markdown"]},
    {"url": "https://example.org", "formats": ["markdown"]}
  ]
}

Save the returned batch_id. Poll with a delay between requests, adding include_results=true to retrieve individual results.

curl "https://api.finedata.ai/api/v1/async/batch/YOUR_BATCH_ID?include_results=true" \
  -H "x-api-key: fd_your_api_key"

Stop polling at completed, partial or failed. For a single job, terminal states are completed, failed and cancelled; completed output is in result.data. An optional callback_url notifies your public endpoint when work finishes.

Captcha Solving

Set solve_captcha: true to auto-detect and solve (+10 tokens).

TLS Profiles

Set tls_profile to mimic a browser fingerprint.

Proxy & Geo-Targeting

Geo-Targeting

Set proxy_country to an ISO-2 country code to request a proxy exit IP from that country. Works with datacenter, residential, ISP, and mobile proxies at no extra cost. Returns 422 if the country isn't currently supported for the resolved proxy type.

{
  "url": "https://example.com",
  "use_residential": true,
  "proxy_country": "DE"
}

Bring Your Own Proxy (BYOP)

Save your own proxy list as a profile in the dashboard, then reference it with proxy_profile_id. Proxies are encrypted at rest. BYOP charges a flat +1 token instead of the vendor proxy surcharge, and is mutually exclusive with use_residential / use_isp / use_mobile / proxy_country.

{
  "url": "https://example.com",
  "proxy_profile_id": 42,
  "proxy_sticky": true
}

Available on PAYG, Team S/M/L and Scaling, or with an account override. Combine with proxy_sticky: true to keep the same exit IP for an entire browser session — useful for anti-bot flows where warmup and API calls must share one IP.

Error Codes

These are API HTTP errors. Inspect the response's detail for the cause. A target-page failure can instead arrive in a scrape result with success: false; inspect its status_code and metadata before retrying.

MCP Integration

Connect FineData to Claude Desktop, Cursor IDE, and other AI agents via MCP (v0.3.1). Full setup, tool reference, OAuth sign-in and cost guidance: the MCP server page. Tools: scrape_url (GET), send_http_request (POST/PUT/PATCH/DELETE), scrape_async, get_job_status, cancel_job, list_jobs, batch_scrape, get_batch_status, get_usage. Start with a default request. Add rendering or routing only when the page needs it; use the tool's error hints rather than enabling the most expensive mode by default.

{
  "mcpServers": {
    "finedata": {
      "command": "npx",
      "args": ["-y", "@finedata/mcp-server"],
      "env": { "FINEDATA_API_KEY": "fd_your_api_key" }
    }
  }
}

Remote (Streamable HTTP):

{
  "mcpServers": {
    "finedata": {
      "url": "https://mcp.finedata.ai/mcp",
      "headers": { "Authorization": "Bearer fd_your_api_key" }
    }
  }
}

Rate Limits

Free plans block when exhausted. Paid plans allow overage at $0.55/1K tokens.