# 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](https://shotkit.net/docs/options/essentials.md) · [Viewport](https://shotkit.net/docs/options/viewport.md) · [Image](https://shotkit.net/docs/options/image.md) · [Full page](https://shotkit.net/docs/options/full-page.md) · [Clip](https://shotkit.net/docs/options/clip.md) · [PDF](https://shotkit.net/docs/options/pdf.md) · [Animation](https://shotkit.net/docs/options/animation.md) · [Emulation](https://shotkit.net/docs/options/emulation.md) · [Customization](https://shotkit.net/docs/options/customization.md) · [Blocking](https://shotkit.net/docs/options/blocking.md) · [Wait](https://shotkit.net/docs/options/wait.md) · [Request](https://shotkit.net/docs/options/request.md) · [Geolocation](https://shotkit.net/docs/options/geolocation.md) · [Caching](https://shotkit.net/docs/options/caching.md) · [Metadata](https://shotkit.net/docs/options/metadata.md) · [Async & webhooks](https://shotkit.net/docs/options/async.md) · [Errors](https://shotkit.net/docs/options/errors.md) · [OpenAI vision](https://shotkit.net/docs/options/vision.md).

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