Screenshot Guide

The Screenshot endpoint captures a pixel-perfect screenshot of any URL. It renders JavaScript, blocks ads and cookie banners, handles CAPTCHAs, and can emulate any device or viewport size. Costs 5 credits per request. Endpoint: POST https://api.geekflare.com/screenshot

Install the official SDK: npm install @geekflare/api-node or pip install geekflare-api

Basic Screenshot

Capture a screenshot and get back a CDN URL to the image.

import { GeekflareClient } from '@geekflare/api-node';

const client = new GeekflareClient({ apiKey: 'YOUR_API_KEY' });
const result = await client.screenshot({ url: 'https://example.com' });
console.log(result);

from geekflare_api.client import GeekflareClient
from geekflare_api.models import ScreenshotDto

with GeekflareClient(api_key='YOUR_API_KEY') as client:
    result = client.screenshot(ScreenshotDto(url='https://example.com'))
    print(result)

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Response

{
  "timestamp": 1778737930991,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "url": "https://example.com",
    "type": "png",
    "device": "desktop",
    "fullPage": false,
    "blockAds": true,
    "hideCookie": true,
    "skipCaptcha": true,
    "addTimestamp": false,
    "test": { "id": "abc123" }
  },
  "data": "https://cdn.geekflare.com/tests/screenshot/kbi6d206g87ituahb7icwtpr.png"
}

Full-Page Screenshot

Capture the entire scrollable page, not just the viewport.

const result = await client.screenshot({
  url: 'https://example.com',
  fullPage: true
});

result = client.screenshot(ScreenshotDto(url='https://example.com', full_page=True))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "fullPage": true}'

Capture a Specific Element (CSS Selector)

Capture only the element matching a CSS selector instead of the full viewport or page. Combine with fallbackToFullPage to gracefully fall back to a full-page capture if the selector isn’t found, instead of failing the request.

const result = await client.screenshot({
  url: 'https://example.com',
  selector: '.hero-section',
  fallbackToFullPage: true
});

result = client.screenshot(ScreenshotDto(
    url='https://example.com',
    selector='.hero-section',
    fallback_to_full_page=True
))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "selector": ".hero-section", "fallbackToFullPage": true}'

If selector is omitted, the endpoint captures the full viewport (or full page, if fullPage is true). If selector is set and no matching element is found, the request fails unless fallbackToFullPage is true.

Image Format and Quality

Choose between PNG, JPEG, or WebP output and control quality for JPEG/WebP.

const result = await client.screenshot({
  url: 'https://example.com',
  type: 'webp',
  quality: 85
});

result = client.screenshot(ScreenshotDto(url='https://example.com', type='webp', quality=85))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "type": "webp", "quality": 85}'

Device Emulation

Emulate a mobile device to capture mobile-specific layouts.

const result = await client.screenshot({
  url: 'https://example.com',
  device: 'mobile'
});

result = client.screenshot(ScreenshotDto(url='https://example.com', device='mobile'))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "device": "mobile"}'

Custom Viewport

Set a custom viewport width, height, or page height for partial screenshots. Use captureBeyondViewport to allow the capture to include content that extends beyond the configured viewport dimensions.

const result = await client.screenshot({
  url: 'https://example.com',
  viewportWidth: 1440,
  viewportHeight: 900,
  pageHeight: 1200,
  captureBeyondViewport: true
});

result = client.screenshot(ScreenshotDto(
    url='https://example.com',
    viewport_width=1440,
    viewport_height=900,
    page_height=1200,
    capture_beyond_viewport=True
))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "viewportWidth": 1440, "viewportHeight": 900, "pageHeight": 1200, "captureBeyondViewport": true}'

Retina / High-DPI

Capture Retina-quality screenshots using a higher device scale factor.

const result = await client.screenshot({
  url: 'https://example.com',
  scaleFactor: 2
});

result = client.screenshot(ScreenshotDto(url='https://example.com', scale_factor=2))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "scaleFactor": 2}'

Dark Mode

Render the page in dark mode before capturing.

const result = await client.screenshot({
  url: 'https://example.com',
  theme: 'dark'
});

result = client.screenshot(ScreenshotDto(url='https://example.com', theme='dark'))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "theme": "dark"}'

Highlight Links (AI Vision)

Draw visible borders around all clickable links, buttons, and inputs. Useful for AI vision models and LLM web browsing agents.

const result = await client.screenshot({
  url: 'https://example.com',
  highlightLinks: true
});

result = client.screenshot(ScreenshotDto(url='https://example.com', highlight_links=True))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "highlightLinks": true}'

Remove Background

Remove the page background for transparent PNG output. Useful for design tools.

const result = await client.screenshot({
  url: 'https://example.com',
  removeBackground: true,
  type: 'png'
});

result = client.screenshot(ScreenshotDto(
    url='https://example.com',
    remove_background=True,
    type='png'
))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "removeBackground": true, "type": "png"}'

Add Timestamp

Add a timestamp watermark to the screenshot for audit trails or monitoring.

const result = await client.screenshot({
  url: 'https://example.com',
  addTimestamp: true
});

result = client.screenshot(ScreenshotDto(url='https://example.com', add_timestamp=True))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "addTimestamp": true}'

Proxy Routing

Route the browser through a specific country’s IP to capture geo-specific or localized content.

const result = await client.screenshot({
  url: 'https://example.com',
  proxyCountry: 'de'
});

result = client.screenshot(ScreenshotDto(url='https://example.com', proxy_country='de'))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "proxyCountry": "de"}'

Delayed Screenshot

Wait a set number of seconds after page load before capturing. Useful for pages with animations or slow-loading widgets.

const result = await client.screenshot({
  url: 'https://example.com',
  delay: 3
});

result = client.screenshot(ScreenshotDto(url='https://example.com', delay=3))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "delay": 3}'

Disable Animations

Freeze CSS animations and transitions before capturing. Produces cleaner, more consistent screenshots.

const result = await client.screenshot({
  url: 'https://example.com',
  disableAnimations: true
});

result = client.screenshot(ScreenshotDto(url='https://example.com', disable_animations=True))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "disableAnimations": true}'

Inline Response

By default, the endpoint returns a CDN URL pointing to the generated image (see data in the response above). Set inline: true to receive the image data directly in the response instead, which can save a round trip if you don’t need the image hosted.

const result = await client.screenshot({
  url: 'https://example.com',
  inline: true
});

result = client.screenshot(ScreenshotDto(url='https://example.com', inline=True))

curl -X POST https://api.geekflare.com/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "inline": true}'

All Parameters

Parameter	Type	Default	Description
`url`	string	required	Target URL
`device`	`desktop` \| `mobile`	`desktop`	Device to emulate
`type`	`png` \| `jpeg` \| `webp`	`png`	Image format
`fullPage`	boolean	`false`	Capture full scrollable page
`selector`	string	—	CSS selector for the element to capture
`fallbackToFullPage`	boolean	`false`	Fall back to a full-page capture if `selector` isn’t found
`blockAds`	boolean	`true`	Block ads before capturing
`hideCookie`	boolean	`true`	Remove cookie consent banners
`skipCaptcha`	boolean	`true`	Attempt to bypass CAPTCHAs
`proxyCountry`	string	—	Route browser through country ISO code
`viewportWidth`	number	—	Viewport width in pixels (320–3840)
`viewportHeight`	number	—	Viewport height in pixels (240–2160)
`pageHeight`	number	—	Page height for partial screenshot (100–5000)
`captureBeyondViewport`	boolean	—	Capture content beyond viewport
`scaleFactor`	number	—	Device pixel ratio (0.1–5). Use 2–3 for Retina
`theme`	`light` \| `dark` \| `auto`	`auto`	Color scheme
`quality`	number	—	Image quality 10–100 (JPEG/WebP only)
`delay`	number	—	Seconds to wait after page load (0–10)
`highlightLinks`	boolean	`false`	Draw borders around links/buttons (AI vision)
`removeBackground`	boolean	`false`	Remove page background (PNG only)
`disableAnimations`	boolean	`false`	Freeze CSS animations before capture
`addTimestamp`	boolean	`false`	Add timestamp watermark
`inline`	boolean	`false`	Return image data inline instead of a CDN URL

Credits

Mode	Credits
Screenshot	5

Node.js SDK

npm install @geekflare/api-node

Python SDK

pip install geekflare-api

Getting started

Quickstarts

Guides

MCP Server

Capabilities

Best Practices

Troubleshooting

Changelog

Basic Screenshot

Full-Page Screenshot

Capture a Specific Element (CSS Selector)

Image Format and Quality

Device Emulation

Custom Viewport

Retina / High-DPI

Dark Mode

Highlight Links (AI Vision)

Remove Background

Add Timestamp

Proxy Routing

Delayed Screenshot

Disable Animations

Inline Response

All Parameters

Credits

Node.js SDK

Python SDK

​Basic Screenshot

​Full-Page Screenshot

​Capture a Specific Element (CSS Selector)

​Image Format and Quality

​Device Emulation

​Custom Viewport

​Retina / High-DPI

​Dark Mode

​Highlight Links (AI Vision)

​Remove Background

​Add Timestamp

​Proxy Routing

​Delayed Screenshot

​Disable Animations

​Inline Response

​All Parameters

​Credits

Node.js SDK

Python SDK

Basic Screenshot

Full-Page Screenshot

Capture a Specific Element (CSS Selector)

Image Format and Quality

Device Emulation

Custom Viewport

Retina / High-DPI

Dark Mode

Highlight Links (AI Vision)

Remove Background

Add Timestamp

Proxy Routing

Delayed Screenshot

Disable Animations

Inline Response

All Parameters

Credits