Skip to Content

pdf

save a web page as a pdf: a real document with selectable text and working links, with the page’s backgrounds printed and no header or footer added. ask for it with extract.pdf on POST /api/scrape or POST /api/scrape/async. {} takes every default.

three behaviors to design around:

  • the pdf comes back as a signed link that expires 24 hours after the scrape. save the file itself, not the link (see retention).
  • a pdf request always runs in a browser. this adds latency compared to an http scrape.
  • in rare cases a pdf can’t be made. when that happens, the rest of your requested outputs are delivered as normal, the pdf field is left out and warnings carries pdf_unavailable. a request for only a pdf fails with an error instead (see when no pdf can be made).

save a page as a pdf

curl -X POST https://api.crawlbrulee.com/api/scrape \ -H "Authorization: Bearer $CRAWLBRULEE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "extract": { "pdf": {} } }'

response (condensed):

{ "url": "https://example.com", "requested_url": "https://example.com", "page_status_code": 200, "content_type": "text/html", "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples ...", "metadata": { "title": "Example Domain" }, "pdf": { "url": "https://cdn.crawlbrulee.com/scrape_assets/documents/pdfs/abc123/def456/page.pdf?token=HS256-…&expires=1791374400", "bytes": 184320 }, "response_meta": { "usage": { "total_credit_cost": 5, "engine_credit_cost": 5, "proxy_multiplier": 1, "screenshot_slicing_credit_cost": 0, "zero_data_retention_credit_cost": 0, "engine": "screenshot", "proxy": "basic" } } }

markdown and metadata are on by default, so they come back too. to get only the pdf, see a pdf-only request.

options

fieldtypedefaultdescription
layoutstring"pages""pages": the page on sheets of paper. "single_page": one long page. see layouts
paperstring"a4""a4" or "letter". only with layout: "pages"
landscapebooleanfalseturn the paper sideways. only with layout: "pages"
mediastring"screen""screen": the page as it looks on screen. "print": the site’s own print style

paper and landscape are refused with layout: "single_page", whatever their value: the request fails with a 400 validation_error and costs nothing.

{ "url": "https://example.com", "extract": { "pdf": { "layout": "pages", "paper": "letter", "landscape": true, "media": "print" } } }

layouts

  • pages (the default) puts the page on sheets of paper, laid out as in the browser window and shrunk to fit the paper width. the window is the desktop default, or the screenshot’s device and viewport when the request also asks for a screenshot.
  • single_page makes one page as wide as the browser window and as tall as the web page, up to 15,000px. a taller page goes on over more pages, and warnings carries pdf_single_page_overflow.

media

screen gives you the page as it looks on screen. print uses the site’s own print style, which on many sites hides menus and images. a site without a print style looks the same as with screen.

the response

the pdf comes back in a top-level pdf object, next to the other outputs.

fieldtypedescription
urlstringsigned link to download the pdf, expires 24 hours after the scrape
bytesintegersize of the pdf file in bytes

a pdf can be at most 50 MB. a page that would make a bigger one comes back without a pdf, with the pdf_unavailable warning.

warnings

warning codewhat it means
pdf_unavailableyou asked for a pdf, but the page came back without one. the rest of the result is there; the pdf field is left out
pdf_single_page_overflowa single_page pdf was taller than the 15,000px page limit, so it goes on over more pages

warnings is stored with the result, so a cache hit and an async result fetch carry the same codes. see limits and truncation for every warning code.

retention

pdf links work like screenshot links. they are signed and expire 24 hours after the scrape, and a pdf isn’t publicly accessible. download the file and keep it, not the link.

  • for an async scrape, the 24 hours start when you submit the job. fetching the result again doesn’t restart them.
  • to get a new link later, scrape the page again.
  • use the link exactly as returned. any change to it, such as a tracking parameter that some tools add when you open a link, breaks the signature, and the request is refused.

a pdf made for a request with zero data retention is also deleted after those 24 hours.

a pdf-only request

markdown and metadata are on by default. to get only the pdf, turn both off:

{ "url": "https://example.com", "extract": { "pdf": {}, "markdown": false, "metadata": false } }

that is a pdf-only request: it asks for a pdf and no other output. when no pdf can be made, such a request fails instead of returning an empty 200. a request for a pdf and a screenshot and nothing else works the same way. see when no pdf can be made.

with a screenshot

ask for a pdf and a screenshot in one request, and both are made from the same page in the same browser window. the pdf’s pages layout uses the screenshot’s device and viewport, and its color_scheme: with color_scheme: "dark", the pdf shows the site’s dark theme too. in a request with a pdf and no screenshot, the pdf is made with the light theme, because the pdf has no color setting of its own.

{ "url": "https://example.com", "extract": { "pdf": { "layout": "single_page" }, "screenshot": { "type": "full_page", "color_scheme": "dark" } } }

a pdf and a screenshot in one request are billed once (see credits).

when no pdf can be made

in rare cases a pdf can’t be made: the page would be over 50 MB as a pdf, it takes too long, or the browser could not load the page. what happens depends on what else you requested:

  • the request also asks for other outputs (markdown, links, …): the scrape succeeds. every other requested field is delivered as normal, the pdf field is left out, and warnings carries pdf_unavailable. check for pdf instead of assuming it’s there.
  • the request asks only for a pdf (with markdown: false and metadata: false, and no other output): instead of returning an empty 200, the request fails.
    • the content type can’t be made into a pdf (json, plain text, markdown, xml) → 422 with error name unsupported_pdf_output.
    • the page can be made into a pdf but making it failed → 500.
  • the request asks only for a pdf and a screenshot and the content type can’t be captured: the error is 422 unsupported_screenshot_output, as for a screenshot-only request (see when no screenshot can be delivered).

in these failure cases you’re not billed. the same rules apply to sync scrapes, fresh and cached alike.

an async job that asks only for a pdf (or only for a pdf and a screenshot) and gets no capture ends as failed, not billed. fetching its result from GET /api/scrape/result/{job_id} answers the same 422 as above when the content type can’t be captured, and 400 job_failed when making the capture failed. see errors for the error format.

credits

a pdf request costs what a screenshot costs: the 5-credit screenshot engine base before the proxy multiplier, so 5 credits on basic and 25 on advanced. the response reports engine: "screenshot".

  • a pdf and a screenshot in one request are billed once.
  • when the pdf can’t be made, the request costs what it would cost without it.
  • slices on a screenshot add their flat +1 as usual.

see credits & pricing for the full formula.

caching

a pdf is cached like a screenshot. a cached copy of the page answers a pdf request only when it has a pdf made with the same settings (layout, paper, landscape, media) in the same browser window: when the request also asks for a screenshot, the same device, viewport and color_scheme. otherwise the page is scraped fresh. cache.max_age: 0 always makes a new pdf. a cache hit costs 0 credits. see caching.