---
title: "Take a screenshot (alias of /api/v1/screenshot)"
method: GET
path: "/api/v1/take"
tags: ["Screenshots"]
---

# Take a screenshot (alias of /api/v1/screenshot)

`GET /api/v1/take`

## Request

- Base URL: `https://curlshot.com`
- URL: `https://curlshot.com/api/v1/take`
- Auth: one of:
  - API key in query parameter `access_key`
  - API key in header `X-Access-Key`
  - HTTP bearer

Render a URL, HTML or Markdown into a PNG, JPEG, WebP or PDF. Exactly one of `url`, `html` or `markdown` is required. A successful render uses one screenshot of the monthly quota; cache hits and failed renders are free.

## Query parameters

- `url` string
- `html` string
- `markdown` string
- `format` 'png' | 'jpeg' | 'webp' | 'pdf' | 'mp4' | 'webm' | 'gif'
- `image_quality` integer
- `image_width` integer
- `image_height` integer
- `omit_background` boolean
- `response_type` 'by_format' | 'json'
- `viewport_width` integer
- `viewport_height` integer
- `device_scale_factor` number
- `viewport_device` 'iphone_se' | 'iphone_12' | 'iphone_13' | 'iphone_13_mini' | 'iphone_14' | 'iphone_14_plus' | 'iphone_14_pro' | 'iphone_14_pro_max' | 'iphone_15' | 'iphone_15_plus' | 'iphone_15_pro' | 'iphone_15_pro_max' | 'iphone_16' | 'iphone_16_plus' | 'iphone_16_pro' | 'iphone_16_pro_max' | 'pixel_5' | 'pixel_7' | 'pixel_8' | 'pixel_8_pro' | 'pixel_9' | 'pixel_9_pro' | 'galaxy_s23' | 'galaxy_s24' | 'galaxy_s24_ultra' | 'galaxy_a54' | 'ipad' | 'ipad_mini' | 'ipad_air' | 'ipad_pro_11' | 'ipad_pro_13' | 'galaxy_tab_s9' | 'pixel_tablet' | 'macbook_air_13' | 'macbook_pro_14' | 'macbook_pro_16' | 'laptop_hd' | 'laptop_hidpi' | 'desktop_hd' | 'desktop_full_hd' | 'desktop_qhd' | 'desktop_4k' | 'imac_24'
- `viewport_mobile` boolean
- `viewport_landscape` boolean
- `full_page` boolean
- `full_page_scroll` boolean
- `full_page_max_height` integer
- `selector` string
- `clip_x` integer
- `clip_y` integer
- `clip_width` integer
- `clip_height` integer
- `wait_until` 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
- `delay` number
- `timeout` number
- `wait_for_selector` string
- `dark_mode` boolean
- `reduced_motion` boolean
- `media_type` 'screen' | 'print'
- `hide_selectors` string[]
- `styles` string
- `scripts` string
- `click` string
- `user_agent` string
- `headers` string[]
- `cookies` string[]
- `authorization` string
- `time_zone` string
- `block_ads` boolean
- `block_trackers` boolean
- `block_cookie_banners` boolean
- `block_chats` boolean
- `block_resources` string[]
- `block_requests` string[]
- `pdf_paper_format` 'a0' | 'a1' | 'a2' | 'a3' | 'a4' | 'a5' | 'a6' | 'letter' | 'legal' | 'tabloid' | 'ledger'
- `pdf_landscape` boolean
- `pdf_print_background` boolean
- `pdf_margin` string
- `pdf_margin_top` string
- `pdf_margin_right` string
- `pdf_margin_bottom` string
- `pdf_margin_left` string
- `pdf_fit_one_page` boolean
- `video_duration` number
- `video_max_duration` number
- `video_fps` integer
- `video_scroll` boolean
- `video_scroll_back` boolean
- `video_scroll_easing` 'ease_in_out' | 'linear'
- `cache` boolean
- `cache_ttl` integer
- `cache_key` string
- `async` boolean
- `webhook_url` string
- `webhook_sign` boolean
- `signature` string
- `expires` integer

## Response `200`

The rendered file. With `response_type=json` the body is JSON describing the stored file instead.

- ScreenshotResult
  - `id` string, required: Reference id of the render.
  - `url` string, uri, nullable, required: Link to the stored file. It carries its own expiring token and needs no access key.
  - `format` 'png' | 'jpeg' | 'webp' | 'pdf' | 'mp4' | 'webm' | 'gif', required
  - `bytes` integer, required
  - `width` integer, nullable
  - `height` integer, nullable
  - `render_ms` integer, nullable
  - `cached` boolean: True when a stored copy was served.
  - `expires_at` string, date-time, nullable: When the stored file is removed and its link stops working.

## Other responses

- `202`: Returned when `async=true`: the render was queued.
- `400`: `invalid_url`: The URL is not valid. Use a full http:// or https:// address. `invalid_options`: One or more options are not valid. `invalid_request`: The request could not be read. Send a JSON object.
- `401`: `access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.
- `402`: `quota_exceeded`: The screenshot quota for this billing period is used up.
- `403`: `host_not_allowed`: This host cannot be rendered. Private, local and internal network addresses are blocked. `signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `email_not_verified`: The email address of this account is not verified yet. Open the verification link we emailed you, then retry. `feature_not_available`: Your plan does not include this feature. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`.
- `413`: `content_too_large`: The request or the rendered output is larger than the allowed size.
- `422`: `selector_not_found`: No element on the page matches the selector. `page_blocked`: The site blocked the automated browser: it answered with a bot check, a block page or a blank page instead of its content. The render was not billed.
- `429`: `concurrency_limit`: Too many renders are running at once for this account. Retry in a moment. `rate_limited`: Too many requests. Slow down and retry after the indicated delay. `queue_limit`: Too many async jobs of this account are waiting to render. Wait for some to finish, then retry. `failure_limit`: Too many renders of this account failed in the last minute. Fix the failing requests, then retry after the indicated delay.
- `500`: `internal_error`: Something went wrong while rendering. The render was not billed; please retry.
- `502`: `navigation_failed`: The page could not be loaded. Check that the address is correct and publicly reachable.
- `503`: `renderer_busy`: All render slots are busy right now. Retry in a moment. `renderer_unavailable`: The rendering service is temporarily unavailable. Retry in a moment. `service_unavailable`: The service is temporarily unavailable. Retry in a moment.
- `504`: `timeout`: The page took too long to render. Try a larger `timeout` or a lighter `wait_until`.

---

[API](https://skmtc.dev/curlshot/apis/curlshot-api.md) · [All operations](https://skmtc.dev/curlshot/apis/curlshot-api/llms.txt) · [OpenAPI document](https://skmtc.dev/curlshot/apis/curlshot-api/revisions/2022db7875af?raw)