Notion pages look simple in a browser but they're surprisingly hard to screenshot programmatically. The content loads block by block through JavaScript — text, images, databases, embedded files all render at different speeds. Fire a screenshot too early and you get a half-loaded page with blank spaces where content should be.
I've debugged enough broken Notion captures to know what goes wrong. This post walks through the specific problems and shows how to get clean screenshots of ScreenshotRun's API — public pages, private workspaces, databases, dark mode, the whole thing.
Why Notion pages load so slowly
Notion is a React SPA that fetches page content through its own API after the initial HTML shell loads. Each block (paragraph, heading, image, toggle, database view) is a separate component that renders independently. A page with 50 blocks might need 2-3 seconds just for the text to appear. Add images, embedded files, or a database view and you're looking at 5-8 seconds before everything has painted.
Standard browser events don't help here. DOMContentLoaded fires almost instantly (the HTML shell is tiny). networkidle0 — which waits for zero network requests over 500ms — fires too early because Notion batches its API calls with gaps between them. The browser thinks the page is done loading while Notion is still fetching the next batch of blocks.
The fix is simple but the timing depends on page complexity:
curl "https://api.screenshotrun.com/v1/screenshots/capture?url=https://myworkspace.notion.site/Project-Docs-abc123def456&format=png&delay=5000&full_page=true" \
-H "Authorization: Bearer YOUR_API_KEY" \
--output notion-page.png
A 5000ms delay works for most Notion pages. Heavy pages with inline databases or lots of embedded content might need 7000-8000ms. I'd rather wait an extra two seconds than re-capture a page with missing blocks.
Public pages vs. private workspaces
Notion has two visibility modes that matter for screenshots. Published pages (shared via "Share to web") are accessible to anyone with the URL. Workspace pages (the default) require authentication.
Published pages are straightforward — pass the URL, set your delay, done. The URL format is workspace.notion.site/Page-Title-hexid. Older notion.so/hexid links redirect to the .notion.site domain automatically, so both work.
Private pages need a session cookie. Notion uses a token_v2 cookie for authentication:
curl "https://api.screenshotrun.com/v1/screenshots/capture?url=https://myworkspace.notion.site/Internal-Wiki-abc123&format=png&delay=6000&full_page=true&cookies=token_v2%3Dv02%253Auser%253A...%3B%20domain%3D.notion.site" \
-H "Authorization: Bearer YOUR_API_KEY" \
--output notion-private.png
To grab the token: open Notion in Chrome, hit F12, go to Application > Cookies > notion.site, copy the token_v2 value. These tokens last a few weeks before Notion rotates them. If your automated captures start returning login pages, the token expired — refresh it from your browser.
The page width problem
Notion centers its content in a column roughly 900px wide (with "Full width" off) or about 1200px (with "Full width" on). The rest of the viewport is empty whitespace. A 1440px-wide screenshot gives you content in the middle with 200-300px of blank space on each side.
Two approaches to fix this. You can match your viewport width to the content width:
curl "https://api.screenshotrun.com/v1/screenshots/capture?url=https://myworkspace.notion.site/Meeting-Notes-abc123&format=png&width=960&delay=5000&full_page=true" \
-H "Authorization: Bearer YOUR_API_KEY" \
--output notion-narrow.png
Or use CSS injection to strip the padding and let the content fill the viewport:
curl "https://api.screenshotrun.com/v1/screenshots/capture?url=https://myworkspace.notion.site/Meeting-Notes-abc123&format=png&delay=5000&full_page=true&css=.notion-page-content,.layout-content{max-width:100%%!important;padding:0 24px!important}" \
-H "Authorization: Bearer YOUR_API_KEY" \
--output notion-full-width.png
I prefer setting width=960 for most cases. The CSS injection approach works but Notion occasionally changes their class names during updates, which breaks the selectors.
Capturing database views
Notion databases (tables, boards, galleries, timelines, calendars) are the heaviest components on any page. A full table with 100+ rows loads its data in chunks — first the visible rows, then more as you scroll. Board views fetch each column independently. Gallery views lazy-load card cover images.
For inline databases (embedded within a page), full_page=true with a generous delay captures whatever rows are initially loaded. But Notion caps the visible rows — it shows about 25-50 rows before adding a "Load more" button. You won't get all 500 rows in a single screenshot without interaction.
For full-page database views, you usually want a viewport capture of the current state rather than trying to load everything:
import requests
response = requests.get(
"https://api.screenshotrun.com/v1/screenshots/capture",
params={
"url": "https://myworkspace.notion.site/Task-Database-abc123",
"format": "png",
"width": 1440,
"height": 900,
"delay": 6000,
},
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
with open("notion-database.png", "wb") as f:
f.write(response.content)
I use a wider viewport (1440px) for database views because tables and boards benefit from the extra horizontal space. The 6-second delay gives the database rows and any cover images time to load.
Embedded content and iframes
Notion pages often embed external content: Google Maps, Figma files, YouTube videos, Miro boards, Loom recordings. Each embed is an iframe that loads independently from the host page. Some render fast (YouTube thumbnails appear in under a second), others are slow (Figma can take 4-5 seconds to render a preview).
The delay parameter covers most embeds if you set it high enough. But some iframes refuse to render in headless browsers entirely — they check for user interaction or block automated contexts. For those, you get an empty gray rectangle where the embed should be.
If a specific embed block is the whole point of your capture, use wait_for_selector to target the iframe's loaded state:
curl "https://api.screenshotrun.com/v1/screenshots/capture?url=https://myworkspace.notion.site/Design-Specs-abc123&format=png&delay=5000&wait_for_selector=iframe[src*='figma']&timeout=15000" \
-H "Authorization: Bearer YOUR_API_KEY" \
--output notion-with-figma.png
The wait_for_selector pauses the capture until the Figma iframe appears in the DOM. Combined with the 5-second delay (which runs after the selector is found), this gives the embed enough time to actually render its content.
Dark mode and cover images
Notion respects prefers-color-scheme: dark, so forcing dark mode is one parameter away:
curl "https://api.screenshotrun.com/v1/screenshots/capture?url=https://myworkspace.notion.site/Roadmap-abc123&format=png&dark_mode=true&delay=5000&full_page=true" \
-H "Authorization: Bearer YOUR_API_KEY" \
--output notion-dark.png
Cover images load separately from the page content. They're fetched from Notion's S3-backed CDN and can take 1-2 seconds after the page blocks appear. If your screenshots are missing the cover image (the banner at the top of the page), bump the delay by a second or two. Page icons — the emoji or uploaded image next to the title — load faster but can still lag on pages with custom uploaded icons.
Notion Sites with custom domains
Notion Sites lets teams publish pages under custom domains (docs.yourcompany.com instead of workspace.notion.site). Under the hood, the rendering is identical — same React SPA, same block loading behavior, same timing requirements.
The only difference: some custom domain setups add extra DNS resolution time. If your first capture of a custom-domain Notion site comes back blank, increase the timeout. The delay starts counting after the page begins loading, so a slow DNS lookup eats into your delay budget.
A Node.js script for batch captures
If you're archiving a set of Notion pages (documentation snapshots, weekly board states, project timelines), a batch script keeps things organized:
const fs = require("fs");
const API_KEY = process.env.SCREENSHOTRUN_API_KEY;
const BASE = "https://api.screenshotrun.com/v1/screenshots/capture";
const pages = [
{ url: "https://team.notion.site/Roadmap-abc123", name: "roadmap" },
{ url: "https://team.notion.site/Sprint-Board-def456", name: "sprint" },
{ url: "https://team.notion.site/API-Docs-ghi789", name: "api-docs" },
];
async function capture(page) {
const params = new URLSearchParams({
url: page.url,
format: "png",
full_page: "true",
delay: "6000",
width: "1280",
});
const res = await fetch(`${BASE}?${params}`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
if (!res.ok) {
console.error(`Failed ${page.name}: ${res.status}`);
return;
}
const date = new Date().toISOString().slice(0, 10);
const filename = `notion-${page.name}-${date}.png`;
fs.writeFileSync(filename, Buffer.from(await res.arrayBuffer()));
console.log(`Saved ${filename}`);
}
(async () => {
for (const page of pages) {
await capture(page);
await new Promise(r => setTimeout(r, 1000));
}
})();
Each file gets a date stamp (notion-roadmap-2026-11-19.png) so you can track changes over time without overwriting previous captures. The 1-second gap between requests keeps things polite — Notion doesn't rate-limit the way Reddit does, but spacing out requests is still good practice.
Common failures and how to fix them
Blank page with just the Notion logo. The page either requires authentication (private workspace) or the delay was too short. Try adding token_v2 cookies first. If the page is public, increase delay to 8000ms.
Missing images below the fold. Notion lazy-loads images as you scroll. full_page=true handles this — the API scrolls the page before capture, triggering image loads. If some images still appear as empty boxes, the page likely has a lot of heavy images and needs more delay time.
Database rows cut off. Notion paginates databases internally. The screenshot captures whatever is currently rendered — usually 25-50 rows. For larger datasets, there's no automated way to click "Load more" through a screenshot API. You can capture the database in multiple viewport-sized screenshots, or use Notion's CSV export for the raw data.
Cover image missing. The cover banner loads asynchronously from Notion's CDN. Add 1-2 seconds to your delay. Pages with high-resolution custom cover images (not Unsplash defaults) take longer.
FAQ#
Notion loads content block by block through JavaScript. A screenshot taken before all blocks have rendered will have blank spaces. Increase the delay parameter to 5000-8000ms depending on page complexity. Pages with databases or embedded content need longer delays.
Yes, but you need to pass a session cookie. Notion uses a token_v2 cookie for authentication. Extract it from your browser DevTools (Application > Cookies > notion.site) and pass it via the cookies parameter. These tokens expire every few weeks and need manual refresh.
Notion centers content in a column roughly 900px wide with whitespace on both sides. Set your screenshot viewport width to 960px to match the content width, or use CSS injection to override the max-width and padding on Notion content containers.
Notion paginates databases and only renders 25-50 rows at a time. A full-page screenshot captures whatever rows are currently visible. For larger datasets, capture the database in multiple screenshots or use Notion CSV export for raw data.
Yes. Notion Sites on custom domains use the same React rendering engine as notion.site pages. The same delay, authentication, and CSS injection parameters apply. The only difference is that custom domains may add extra DNS resolution time on the first request.