Options

All 107 options of the shotkit screenshot API: types, defaults, ranges and how to pass them.

All 107 options, grouped as in the playground: Essentials · Viewport · Image · Full page · Clip · PDF · Animation · Emulation · Customization · Blocking · Wait · Request · Geolocation · Caching · Metadata · Async & webhooks · Errors · OpenAI vision.

Passing options

Every option works in both request styles:

POST a JSON body: booleans and numbers as JSON values, lists as arrays ("block_resources": ["font", "media"]).
GET with a query string: true/false for booleans, and repeat a key for lists (block_resources=font&block_resources=media). Enum lists also accept commas (wait_until=load,networkidle2), and list options accept newlines.

Unknown options are rejected with invalid_parameter, so typos don't silently do nothing. Empty values are ignored.

All options

Option	Type	Default	Description
`url`	string		URL of the site to screenshot.
`html`	string		HTML to render instead of a URL.
`markdown`	string		Markdown to render instead of a URL.
`format`	enum	`jpg`	Response format.
`response_type`	enum	`by_format`	Return the file, JSON metadata, or nothing.
`selector`	string		CSS selector of the element to capture.
`selector_scroll_into_view`	boolean	`true`	Scroll to the element to trigger lazy content.
`capture_beyond_viewport`	boolean		Capture parts outside the viewport (full page / selector).
`scroll_into_view`	string		Scroll this selector to the top before capture.
`scroll_into_view_adjust_top`	number	`0`	Pixel offset after scroll_into_view.
`attachment_name`	string		Download filename (extension added).
`external_identifier`	string		Your ID, echoed in webhook headers.
`include_shadow_dom`	boolean	`false`	Include shadow roots in html/markdown output.
`viewport_device`	enum		Emulate a device preset (sets size, DPR, UA, touch).
`viewport_width`	number	`1280`	Viewport width in px.
`viewport_height`	number	`1024`	Viewport height in px.
`device_scale_factor`	number	`1`	Device pixel ratio (1–5). Animated formats record at 1×.
`viewport_mobile`	boolean	`false`	Respect the meta viewport tag.
`viewport_has_touch`	boolean	`false`	Enable touch events.
`viewport_landscape`	boolean	`false`	Landscape orientation.
`image_quality`	number	`80`	Quality for lossy formats and video (0–100).
`image_width`	number		Resize output to fit this width (keeps ratio).
`image_height`	number		Resize output to fit this height (keeps ratio).
`omit_background`	boolean	`false`	Transparent background (PNG only).
`full_page`	boolean	`false`	Capture the full scrollable page.
`full_page_scroll`	boolean		Scroll to bottom first to load lazy images (auto with full_page).
`full_page_scroll_delay`	number	`400`	Delay between scroll steps (ms).
`full_page_scroll_by`	number		Pixels per scroll step (default: viewport height).
`full_page_max_height`	number		Cap the full-page height (px).
`full_page_slices`	boolean	`false`	Split into vertical slices (URLs returned).
`full_page_slice_height`	number	`4000`	Max height per slice.
`full_page_slice_overlap_height`	number	`0`	Overlap between slices.
`clip_x`	number		Clip area X.
`clip_y`	number		Clip area Y.
`clip_width`	number		Clip area width.
`clip_height`	number		Clip area height.
`pdf_print_background`	boolean	`false`	Print background graphics.
`pdf_fit_one_page`	boolean	`false`	Fit the whole page on one PDF page.
`pdf_landscape`	boolean	`false`	Landscape orientation.
`pdf_paper_format`	enum	`letter`	Paper size.
`pdf_margin`	string		Margin for all sides (e.g. 20px, 1cm).
`pdf_margin_top`	string		Top margin override.
`pdf_margin_right`	string		Right margin override.
`pdf_margin_bottom`	string		Bottom margin override.
`pdf_margin_left`	string		Left margin override.
`animation_duration`	number	`3`	Seconds to record. With format=webp, records an animated WebP.
`animation_fps`	number		Frames per second (default: 10 for gif/webp, 30 for video).
`animation_scroll`	boolean	`false`	Scroll smoothly from the current position to the bottom while recording.
`dark_mode`	boolean		Emulate prefers-color-scheme: dark. Otherwise pages render in light mode.
`reduce_motion`	boolean	`false`	Actively finish/pause animations and videos.
`reduced_motion`	boolean		Emulate prefers-reduced-motion: reduce.
`media_type`	enum		CSS media type.
`hide_selectors`	list		Hide every element matching each selector.
`styles`	string		CSS injected before capture.
`scripts`	string		JavaScript executed before capture.
`scripts_wait_until`	enum list		Wait for these events after scripts run.
`click`	string		Click this selector before capture.
`hover`	string		Hover this selector before capture.
`error_on_click_selector_not_found`	boolean	`true`	Fail if the click target is missing.
`error_on_hover_selector_not_found`	boolean	`true`	Fail if the hover target is missing.
`block_cookie_banners`	boolean	`false`	Hide cookie / GDPR banners.
`block_banners_by_heuristics`	boolean	`false`	Aggressive heuristic banner removal.
`block_chats`	boolean	`false`	Hide chat widgets (Intercom, Crisp, Drift…).
`block_ads`	boolean	`false`	Block ad networks.
`block_trackers`	boolean	`false`	Block analytics / trackers.
`block_requests`	list		Block requests matching wildcard patterns.
`block_resources`	enum list		Block resource types.
`wait_until`	enum list	`load`	Navigation events to wait for.
`delay`	number	`0`	Extra seconds to wait before capture.
`timeout`	number	`60`	Total request timeout (s). Up to 90, or 600 with async (render time only).
`navigation_timeout`	number	`30`	Navigation timeout (s).
`wait_for_selector`	string		Wait for this selector to appear.
`wait_for_selector_algorithm`	enum	`at_least_one`	How comma-separated selectors are matched.
`user_agent`	string		Custom User-Agent.
`authorization`	string		Authorization header for the target.
`headers`	list		Extra headers, one per line.
`cookies`	list		Cookies, one per line.
`time_zone`	enum		Browser time zone.
`proxy`	string		Your HTTP proxy (http://user:pass@host:port).
`bypass_csp`	boolean	`false`	Bypass Content-Security-Policy.
`geolocation_latitude`	number		Latitude.
`geolocation_longitude`	number		Longitude.
`geolocation_accuracy`	number		Accuracy in meters.
`cache`	boolean	`false`	Cache the result and return a CDN URL.
`cache_ttl`	number	`14400`	Cache lifetime in seconds.
`cache_key`	string		Distinguish otherwise identical cached renders.
`metadata_image_size`	boolean	`false`	Return image width/height.
`metadata_page_title`	boolean	`false`	Return the page title.
`metadata_icon`	boolean	`false`	Return the favicon URL.
`metadata_open_graph`	boolean	`false`	Return Open Graph tags.
`metadata_fonts`	boolean	`false`	Return fonts used by the page.
`metadata_content`	boolean	`false`	Also store page content and return its URL.
`metadata_content_format`	enum	`html`	Content format.
`metadata_http_response_status_code`	boolean	`false`	Return the target's HTTP status.
`metadata_http_response_headers`	boolean	`false`	Return the target's HTTP headers.
`async`	boolean	`false`	Return 202 immediately and render in the background.
`webhook_url`	string		POST the result here when done.
`webhook_sign`	boolean	`true`	Sign webhook body with your secret key.
`webhook_errors`	boolean	`false`	Also send errors to the webhook.
`ignore_host_errors`	boolean	`false`	Capture even if the site returns 4xx/5xx.
`error_on_selector_not_found`	boolean	`false`	Fail if selector / scroll_into_view is missing.
`fail_if_request_failed`	list		Fail if a matching sub-request fails.
`fail_if_content_missing`	list		Fail if this text is missing (case-insensitive).
`fail_if_content_contains`	list		Fail if this text is present (case-insensitive).
`openai_api_key`	string		Your OpenAI key (never stored).
`vision_prompt`	string		Prompt sent with the screenshot.
`vision_max_tokens`	number		Max completion tokens.