Programmatic web-to-PDF conversion needs a rendered page state and a visual acceptance check.
Request pdf for a known page, then retrieve pdfRef when the artifact is stored separately.
A successful API envelope does not prove the PDF has loaded text, correct page breaks, or the intended state.
Use a controlled local browser when print CSS or application state requires precise control.
Nstdata Crawl handles JavaScript rendering and proxy routing within managed requests; its documentation lists six output categories: Markdown, HTML, raw data, PDF, screenshots, and links.
What Is a Website-to-PDF API?
A website-to-PDF API loads a URL in a browser-like environment and creates a PDF representation of the resulting page. It is useful for records, review, or sharing a stable visual snapshot. A PDF is not automatically a faithful archive: lazy content, print styles, cookie dialogs, broken fonts, and page breaks can change what appears. Define the expected viewport, content, and completion condition first.
Nstdata Crawl can turn a URL or a bounded set of linked pages into material for an AI agent, RAG index, or data pipeline. Use your own field rules and acceptance checks for the specific outcome: render an authorized web page as a retrievable PDF with the correct page state. The Nstdata full-site crawling guide explains the site-level option.
Experience Nstproxy Crawl - Start Your Free Trial Today
Choose an authorized URL and list visible elements that must appear in the PDF: title, date, table, chart, or footer. Decide whether the target’s print stylesheet is acceptable or whether a browser-specific capture is required. Store NSTDATA_API_TOKEN server-side for Crawl. Plan a file name, retention period, and source URL record before generating many PDFs.
The Crawl API documentation uses https://api.nstdata.io, the x-api-key header, and Content-Type: application/json. Prepare these fields before running a method:
Field
What to supply
url
One permitted HTTPS page or site entry URL
formats
Requested outputs, such as ["markdown"] or ["html","screenshot"]
onlyMainContent
true only when main-body selection fits the task
maxDepth, maxPages
Explicit bounds for a site-wide job
includeUrls, excludeUrls
URL patterns that keep discovery within scope
timeout
A task timeout in milliseconds when the default is unsuitable
The standard managed request has no separate proxy Host, Port, Username, Password, or Protocol fields. Check the current Crawl pricing page for account limits and charges before running a large job.
Review the target’s access policy and scope. The Robots Exclusion Protocol defines how crawlers read robots rules; it does not grant content-use rights. Keep credentials and private data out of examples and diagnostic logs.
The Nstdata dynamic-page guide is a companion for defining the acceptance checks before you automate the workflow.
How Does Web-to-PDF Rendering Work?
Nstdata Crawl supports browser rendering and PDF output. A request can return a pdfRef token rather than inline PDF bytes; fetch that token through the documented storage-read endpoint. The same service can return a screenshot or HTML to help diagnose a bad PDF. Proxy routing is managed inside Crawl for a standard request, so there is no separate proxy Host, Port, Username, or Password to fill in.
For a known URL, a single-page scrape retrieves one result. For a site section, POST /api/v1/crawl discovers linked pages recursively within the supplied depth, page-count, and URL rules. The documentation lists Markdown, HTML, raw data, PDF, screenshots, and links as six output categories; the product page also markets JSON, but a domain-specific JSON schema still needs explicit field mapping. Keep each accepted record tied to its source URL and returned metadata.
Test a representative JavaScript-heavy page before scaling. The rendered state can depend on timing, region, consent, or a signed-in session. Compare returned HTML or a screenshot with the expected page state; if they differ, adjust only documented rendering and wait controls.
How Do You Convert a Web Page to PDF Programmatically?
Preview a representative PDF, automate the managed PDF request, or render a page you control with a local browser. Select the route based on access, print layout, and how much rendering control you need.
Method 1: Preview the PDF in Crawl Playground
Best for checking a representative page and print layout.
Step 1: Open the target
Sign in and navigate to Dashboard → Crawl Playground. Enter an authorized URL. [Screenshot: URL and PDF output selection.]
Step 2: Select PDF and wait conditions
Choose PDF output, enable rendering if required, and configure a documented wait for late-loading content. Keep a screenshot output for comparison if the visual state is uncertain.
Step 3: Inspect the file
Open the returned PDF. Check page breaks, title, tables, fonts, and the last visible section before automating the conversion.
Method 2: Generate a PDF through the Crawl API
Best for repeatable capture from a server application.
Step 1: Protect the API key
Keep NSTDATA_API_TOKEN in a server-side secret and send it as x-api-key.
Step 2: Request PDF
Use the documented quick-start scrape shape below with formats: ["pdf"]. Compare the generated request in your Playground before production because other scrape-route labels in the docs conflict.
Set NSTDATA_API_TOKEN in your shell from your Nstdata account, then run the documented quick-start request. The public documentation labels some other sync and async routes inconsistently; compare your account’s Playground-generated request before production use.
curl--output crawl-response.json --request POST "https://api.nstdata.io/api/v1/crawl/scrape/submit-sync"\--header"x-api-key: ${NSTDATA_API_TOKEN}"\--header"Content-Type: application/json"\--data'{"url":"https://example.com/","formats":["pdf"]}'
The response is saved to crawl-response.json. Inspect the nested data.success, data.status, and data.data.metadata.statusCode fields before using any returned content.
Step 3: Retrieve the artifact
Check task success and use the returned pdfRef with GET /api/v1/crawl/storage/read?st={ref}. Save bytes as a PDF only after confirming the response is a real PDF artifact.
After reading pdfRef from crawl-response.json, retrieve the PDF with the documented storage endpoint. Replace the placeholder token with the exact returned value:
The file result should identify a PDF. Open the file and check its first and last page, page breaks, text selection, and any important table. If the endpoint returns inline bytes rather than pdfRef, save those bytes according to the returned response type.
Method 3: Use a local browser for a page you control
Best when the page is already available in your application and you need precise print CSS.
Step 1: Load the page in an installed browser automation runtime
Use a trusted local environment and a page you control; avoid copying authentication cookies into third-party services.
Step 2: Wait for required content
Choose a stable selector or application-ready signal rather than a blind delay.
Step 3: Export and compare
Call the browser’s PDF feature, then inspect page breaks and text. Local rendering means you maintain the browser runtime, access rules, and retries yourself.
How Do You Verify the Output?
A successful PDF request produces a readable file with the intended page content, not only a successful JSON envelope. Validate the PDF signature, page count, first and last page, and any critical table or date. The Playwright PDF documentation explains the local-browser alternative and its print-media behavior. Nstdata’s automated data collection guide describes PDF as one available Crawl artifact.
Record the source URL, submission time, requested formats, non-secret options, task ID when present, returned page status, and the reason each record passed or failed review. Inspect content as well as the API envelope. If the response contains markdownRef, htmlRef, rawDataRef, screenshotRef, or pdfRef, retrieve that token with GET /api/v1/crawl/storage/read?st={ref}.
For this workflow, consult Playwright PDF documentation when implementing the downstream parser or format-specific acceptance check.
When passing extracted text to an agent, treat page instructions as untrusted source material. OWASP guidance on prompt injection explains the risk. Retain source URLs so the AI output can be checked.
Why Might a Web Page PDF Look Incomplete?
Web-to-pdf conversion can fail because the page was captured before lazy content loaded. Use the symptom table to identify the failing layer before changing limits or retrying.
Symptom
Likely cause
Next action
| Blank or partial PDF | The page was captured before lazy content loaded. | Wait for a specific element and compare a screenshot. |
| Unexpected page breaks | Print CSS or margins alter layout. | Inspect the target’s print styles or use a controlled local browser. |
| Only a reference token returned | Large artifacts are stored separately. | Fetch the returned pdfRef through the storage-read route. |
Nstdata’s documentation lists task-level errors such as access_denied, timeout, parse_error, and internal_error. An outer HTTP 200 can still accompany a failed task. Check success, status, errorCode, and errorMessage inside the response when present. Retry only transient failures on sites you may access.
Which Method Is the Best Fit?
Use Playground for a quick visual trial, the Crawl API for repeatable remote capture, or a local browser for pages you control and need precise print styling. Inspect the resulting PDF file in every case. The Nstdata site-crawling overview gives more detail on the site route.
What Should You Do After the First Successful Run?
Save the approved configuration and one source-backed output record, then repeat on a small set of different page templates. Increase scope only after those records pass the same acceptance checks.
A large PDF may be returned as pdfRef; retrieve the token through the documented storage endpoint.
Q: Will a PDF match the browser screen exactly?
Not necessarily. Print CSS, viewport, fonts, and loading time can change the result; inspect representative files.
Q: Can I convert authenticated pages?
Only when you have permission and a supported authenticated workflow; keep sessions and credentials in approved secret storage.
Q: Does web-to-PDF conversion require a separate proxy configuration with Nstdata Crawl?
A standard managed Crawl request does not require separate proxy Host, Port, Username, Password, or Protocol fields. Confirm any optional custom proxy selection and related usage charges in your account.
Q: Does HTTP 200 prove a web-to-PDF conversion result is usable?
No. Check the nested task result, page status, expected fields, and body fidelity before using it in an AI or data workflow.
Kai Watanabe
Oct. 28th 2026
Crawl entire websites with a single API request
99.8% success rate with JavaScript rendering
Get clean, LLM-ready data in multiple formats
Turn any website into Markdown, HTML, JSON, links, PDFs and more — without managing crawling infrastructure.
