---
title: "Take a screenshot"
method: POST
path: "/v1/sessions/{sessionId}/windows/{windowId}/screenshot"
tags: ["windows"]
---

# Take a screenshot

`POST /v1/sessions/{sessionId}/windows/{windowId}/screenshot`

Take a screenshot of a browser window

## Path parameters

- `sessionId` string, required
- `windowId` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `clientRequestId` string
  - `configuration` TypeScreenshotRequestConfig
    - `screenshot` TypeScreenshotConfig
      - `format` 'base64' | 'url' — Format of the screenshot response. 'base64' returns the image as base64-encoded data. 'url' uploads the screenshot to asset storage and returns a signed download URL. Defaults to 'base64' for viewport scope, 'url' for other scopes.
      - `maxHeight` integer — Maximum height of the screenshot in pixels. The screenshot will be scaled down to fit within this height if necessary, preserving the aspect ratio.
      - `maxWidth` integer — Maximum width of the screenshot in pixels. The screenshot will be scaled down to fit within this width if necessary, preserving the aspect ratio.
      - `quality` integer — JPEG quality (1-100). Note that this option is still in development and may not work as expected.
      - `scope` 'viewport' | 'page' | 'scan' | 'auto' — [Deprecated] Whether to capture the current viewport or whole page. Use visualAnalysis.scope instead. Only viewport is currently supported when used directly.
      - `visualAnalysis` TypeVisualAnalysisConfig
        - `maxScanScrolls` integer — Scan mode only: The maximum number of scrolls to perform. Defaults to 50.
        - `overlapPercentage` integer — The percentage of overlap between screenshot chunks. Defaults to 30 (percent).
        - `partitionDirection` 'vertical' | 'horizontal' | 'bidirectional' — The direction to partition the screenshot into chunks: 'vertical', 'horizontal', or 'bidirectional'. Defaults to 'vertical', which is recommended for most web pages. For optimal results when partitioning in a single direction, ensure the perpendicular dimension does not exceed 1920 pixels.
        - `resultSelectionStrategy` 'first' | 'bestMatch' | 'auto' — [Experimental] The strategy to use for selecting the match using visual analysis. Can be 'auto', 'first' or 'bestMatch'. Defaults to 'auto'. Use 'auto' to let the system decide the best strategy. Use 'first' to select the first visual element that matches the element description. This will favor results that appear higher on the page in the event of multiple matches. Use 'bestMatch' to analyze the complete page and apply judgement to select the best candidate from all potential matches.
        - `scanScrollDelay` integer — Scan mode only: The delay between scrolls in milliseconds. Defaults to 1000 (milliseconds).
        - `scope` 'viewport' | 'page' | 'scan' | 'auto' — Whether to analyze the current viewport or the whole page. Can be 'viewport', 'page', 'scan' or 'auto'. Defaults to 'auto', which provides the simplest out-of-the-box experience for most web pages. Use 'viewport' for analysis of the current browser view only. Use 'page' for a full page analysis. Use 'scan' for a full page analysis on sites that have compatibility or accuracy issues with 'page' mode.
  - `costThresholdCredits` integer — A credit threshold that, once exceeded, will cause the operation to be cancelled. Note that this is *not* a hard limit, but a threshold that is checked periodically during the course of fulfilling the request. A default threshold is used if not specified, but you can use this option to increase or decrease as needed. Set to 0 to disable this feature entirely (not recommended).
  - `timeThresholdSeconds` integer — A time threshold in seconds that, once exceeded, will cause the operation to be cancelled. Note that this is *not* a hard limit, but a threshold that is checked periodically during the course of fulfilling the request. A default threshold is used if not specified, but you can use this option to increase or decrease as needed. Set to 0 to disable this feature entirely (not recommended). This setting does not extend the maximum session duration provided at the time of session creation.

## Response `201`

Created

- TypeAiPromptResponse
  - `data` TypeAiResponseEnvelope, required
    - `modelResponse` string, required
  - `errors` TypeIssue[]
    - `code` string — Issue code.
    - `details` object — Any associated details.
    - `message` string, required — Message describing the issue.
    - `reason` string — Underlying reason for the issue.
  - `meta` TypeExternalSessionAiResponseMetadata, required
    - `clientProvided` TypeClientProvidedResponseMetadata
      - `clientRequestId` string
    - `requestId` string
    - `screenshots` TypeScreenshotMetadata[] — Array containing any requested screenshots from the operation.
      - `dataUrl` string — Base64 encoded data URL of screenshot image data
      - `fileId` string — Unique identifier for the uploaded file
      - `fileName` string — Name of the screenshot file
      - `format` 'base64' | 'url' — Format of the screenshot data
      - `scrollPosition` TypeScreenshotScrollPosition
        - `left` integer, required — Horizontal scroll position in pixels
        - `top` integer, required — Vertical scroll position in pixels
      - `signedDownloadUrl` string — Signed URL for downloading the screenshot (when format is 'url')
      - `urlExpiry` string — Expiration time for the signed URL in ISO format
      - `viewportDimensions` TypeScreenshotViewportDimensions
        - `height` integer, required — Height of the viewport in pixels
        - `width` integer, required — Width of the viewport in pixels
    - `status` 'success' | 'partial' | 'failure', required — Outcome of the operation.
    - `usage` TypeExternalSessionAiResponseMetadataUsage, required
      - `credits` integer, required — The credit usage for this request
      - `id` string, required — The id of the request
  - `warnings` TypeIssue[]
    - `code` string — Issue code.
    - `details` object — Any associated details.
    - `message` string, required — Message describing the issue.
    - `reason` string — Underlying reason for the issue.

---

[API](https://skmtc.net/airtop/apis/airtop-api.md) · [All operations](https://skmtc.net/airtop/apis/airtop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/airtop/airtop-api/revisions/4a02eb5d21ca/schema)