Docs
Side Renders

Side Renders

Generate extra artifacts - HTML, MHTML, markdown, metadata, extracted content and thumbnails - from the same page load as your main render

When Urlbox renders a page, it can generate more than just the main screenshot, PDF or video. Side renders are extra artifacts captured from the same page load as your main render - a markdown conversion of the page, its rendered HTML, page metadata, extracted content like headings, tables and links, resized thumbnails of the screenshot itself, and an MHTML snapshot.

Because side renders are produced while the page is already loaded, they don't trigger a second render. You get multiple outputs from a single request, without paying the render time of loading the page twice.

Each side render is saved alongside the main render and returned as an extra field in the JSON response - so use the API (which returns JSON by default), or add response_type=json to a render link, to see them.

Rendering markdown and HTML alongside a screenshot

The save_markdown and save_html options save an extra text copy of the page in one request - a screenshot for humans and machine-readable content for everything else:

  • save_markdown converts the rendered page to markdown - ideal when you want a screenshot for humans and an LLM-friendly text version of the same page in one request.
  • save_html saves the page's rendered HTML - captured from the live DOM after the page has finished loading, so it includes any changes made by javascript.

Request

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://urlbox.com",
  "save_markdown": true,
  "save_html": true
}'

The response gains a markdownUrl and htmlUrl field for each artifact you requested:

Response

{
  "renderUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.png",
  "size": 258923,
  "renderTime": 4213,
  "queueTime": 165,
  "markdownUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.md",
  "htmlUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.html"
}

If you only want markdown or HTML and no screenshot, you can make it the main render instead by setting format to md or html.

Metadata and extracted content

Urlbox can extract structured information from the page while rendering it.

Page metadata

Setting save_metadata=true extracts the page's metadata: title, description, author, canonical URL, open graph tags, twitter card tags and other meta tags, along with the requested and resolved URLs. The metadata is returned inline in the metadata field of the JSON response, and also saved as a JSON side render linked from metadataUrl:

Request

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://www.bbc.co.uk",
  "save_metadata": true
}'

Response

{
  "renderUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.png",
  "size": 194203,
  "renderTime": 3987,
  "metadataUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.json",
  "metadata": {
    "title": "BBC Home - Breaking News, World News, US News, Sports ...",
    "description": "Visit BBC for trusted reporting on the latest world and US news ...",
    "ogTitle": "BBC Home - Breaking News, World News, US News, Sports ...",
    "ogImage": [{ "url": "https://static.files.bbci.co.uk/.../bbc.png" }],
    "urlRequested": "https://www.bbc.co.uk",
    "urlResolved": "https://www.bbc.co.uk/"
  }
}

Four more options extract specific content from the page:

  • save_headings extracts every heading (h1-h6) with its level, text and id. The response gains a headingsUrl field linking to the saved JSON.
  • save_tables extracts every HTML <table>, with cells organised as rows and columns plus a markdown rendering of each table. The response gains a tablesUrl field.
  • save_structured_data extracts structured data embedded in the page, such as JSON-LD / schema.org markup. The response gains a structuredDataUrl field.
  • save_links extracts every link with its absolute URL and link text, and adds them to the page metadata under links (returned inline in metadata and saved to metadataUrl).

Request

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://en.wikipedia.org/wiki/Screenshot",
  "save_headings": true,
  "save_tables": true,
  "save_structured_data": true,
  "save_links": true
}'

Response

{
  "renderUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.png",
  "size": 231882,
  "renderTime": 5102,
  "metadataUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.json",
  "headingsUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps-headings.json",
  "tablesUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps-tables.json",
  "structuredDataUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps-structured-data.json",
  "metadata": {
    "title": "Screenshot - Wikipedia",
    "links": [
      { "href": "https://en.wikipedia.org/wiki/Screencast", "text": "Screencast" }
    ],
    "urlRequested": "https://en.wikipedia.org/wiki/Screenshot",
    "urlResolved": "https://en.wikipedia.org/wiki/Screenshot"
  }
}

There are also options to record what happened during the render: save_cookies saves the cookies set in the browser by the end of the render, and save_clicks records which elements Urlbox clicked automatically (for example cookie-banner buttons clicked by click_accept). Both are added to the page metadata. save_headers includes the target page's HTTP response headers in the response object of the JSON response.

Thumbnails

The thumbnails option generates up to 5 resized versions of the main render, from the same captured image. It applies to image formats (png, jpeg, webp, avif), and each thumbnail keeps the main render's format.

Each thumbnail spec can set:

  • a key (up to 10 characters) to name the thumbnail,
  • a size: either explicit pixel dimensions (size, or width/height, each between 10 and 2000), or a preset relative to the main render's dimensions: xs (10%), sm (20%), md (30%), lg (40%), xl (50%), 2xl (60%), 3xl (70%), 4xl (80%), 5xl (90%), or the fractions 1/4, 1/2 and 3/4,
  • how to resize: fit (cover, contain, fill, inside, outside), position and a bg colour, with the same semantics as img_fit, img_position and img_bg,
  • a presigned_url to upload the thumbnail straight to your own S3 bucket.

Because the value is an array of objects, use thumbnails with JSON POST requests to the render endpoints:

Request

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://urlbox.com",
  "thumbnails": [
    {
      "key": "small",
      "preset": "sm"
    },
    {
      "key": "card",
      "width": 400,
      "height": 300
    }
  ]
}'

By default the response contains a thumbnails array, one entry per spec:

Response

{
  "renderUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.png",
  "size": 258923,
  "renderTime": 4213,
  "thumbnails": [
    {
      "key": "small",
      "location": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps-small.png",
      "size": 18332
    },
    {
      "key": "card",
      "location": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps-card.png",
      "size": 24560
    }
  ]
}

Set thumbnails_object=true to get the same results as an object keyed by each thumbnail's key instead, useful when you want to look thumbnails up by name rather than position:

Response

{
  "renderUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.png",
  "size": 258923,
  "renderTime": 4213,
  "thumbnails": {
    "small": {
      "location": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps-small.png",
      "size": 18332
    },
    "card": {
      "location": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps-card.png",
      "size": 24560
    }
  }
}

MHTML snapshots

If you need a self-contained archive of the page, save_mhtml=true saves an MHTML snapshot alongside the main render. MHTML bundles the page and its resources into a single file that can be opened in a browser for offline viewing. The response gains an mhtmlUrl field:

Request

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://urlbox.com",
  "save_mhtml": true
}'

Response

{
  "renderUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.png",
  "size": 258923,
  "renderTime": 4213,
  "mhtmlUrl": "https://renders.urlbox.com/ub-temp-renders/renders/.../<render-id>_ps.mhtml"
}

Where side renders are stored

Side renders are stored exactly like the main render. By default they are saved to Urlbox's own cloud storage and served from our CDN, expiring after 30 days.

If you have configured your own S3-compatible storage and set use_s3=true, side renders and thumbnails are saved to your bucket alongside the main render, and the *Url fields in the response point at your bucket (or your cdn_host, if you have set one). See the saving to S3 guide for how to set this up.

Billing

Side renders don't cost extra render time, since they reuse the page load of the main render. Their file sizes, and the file sizes of any thumbnails, do however count toward the render's total output size, which is part of the credit calculation: one render credit is used per 5MB of file size over the included allowance. In practice most side renders (markdown, HTML, metadata JSON, thumbnails) are small, so a typical request with a handful of side renders still costs a single credit.

Related options

See the Side Render Options section of the options reference for every option covered in this guide.