> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.airtop.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airtop.ai/_mcp/server. # Scroll POST https://api.airtop.ai/api/v1/sessions/{sessionId}/windows/{windowId}/scroll Content-Type: application/json Execute a scroll interaction in a specific browser window Reference: https://docs.airtop.ai/api-reference/airtop-api/windows/scroll ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `sessionId` (string, required) — The session id for the window. - `windowId` (string, required) — The Airtop window id of the browser window. ### Body (application/json) This endpoint expects an object. - `clientRequestId` (string, optional) - `configuration` (MicroInteractionConfig, optional) — Request configuration - `costThresholdCredits` (long, optional) — 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). - `scrollBy` (ScrollByConfig, optional) — The amount of pixels/percentage to scroll horizontally or vertically relative to the current scroll position. Positive values scroll right and down, negative values scroll left and up. If a scrollToElement value is provided, scrollBy/scrollToEdge values will be ignored. - `scrollToEdge` (ScrollToEdgeConfig, optional) — Scroll to the top or bottom of the page, or to the left or right of the page. ScrollToEdge values will take precedence over the scrollBy values, and scrollToEdge will be executed first. If a scrollToElement value is provided, scrollToEdge/scrollBy values will be ignored. - `scrollToElement` (string, optional) — A natural language description of where to scroll (e.g. 'the search box', 'username field'). The interaction will be aborted if the target element cannot be found. If provided, scrollToEdge/scrollBy values will be ignored. - `scrollWithin` (string, optional) — A natural language description of the scrollable area on the web page. This identifies the container or region that should be scrolled. If missing, the entire page will be scrolled. You can also describe a visible reference point inside the container. Note: This is different from scrollToElement, which specifies the target element to scroll to. The target may be located inside the scrollable area defined by scrollWithin. - `timeThresholdSeconds` (long, optional) — 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 - `data` (AiResponseEnvelope, required) - `meta` (ExternalSessionAiResponseMetadata, required) - `errors` (list of Issue, optional) - `warnings` (list of Issue, optional) ## Types ### MicroInteractionConfig - `visualAnalysis` (VisualAnalysisConfig, optional) — Optional configuration for visual analysis when locating specified content. - `waitForNavigationConfig` (BrowserWaitNavigationConfig, optional) — Optional configuration for waiting for navigation to complete after clicking the element. ### ScrollByConfig - `xAxis` (string, optional) — The amount of pixels/percentage to scroll horizontally. Percentage values should be between 0 and 100. Positive values scroll right, negative values scroll left. - `yAxis` (string, optional) — The amount of pixels/percentage to scroll vertically. Percentage values should be between 0 and 100. Positive values scroll down, negative values scroll up. ### ScrollToEdgeConfig - `xAxis` (string, optional) — Scroll to the left or right of the page. - `yAxis` (string, optional) — Scroll to the top or bottom of the page. ### AiResponseEnvelope - `modelResponse` (string, required) ### ExternalSessionAiResponseMetadata - `status` (enum, required) — Outcome of the operation. - Allowed values: `success`, `partial`, `failure` - `usage` (ExternalSessionAiResponseMetadataUsage, required) - `clientProvided` (ClientProvidedResponseMetadata, optional) - `requestId` (string, optional) - `screenshots` (list of ScreenshotMetadata, optional) — Array containing any requested screenshots from the operation. ### Issue - `message` (string, required) — Message describing the issue. - `code` (string, optional) — Issue code. - `details` (map from string to any, optional) — Any associated details. - `reason` (string, optional) — Underlying reason for the issue. ### VisualAnalysisConfig - `maxScanScrolls` (long, optional, default: 50) — Scan mode only: The maximum number of scrolls to perform. Defaults to 50. - `overlapPercentage` (long, optional, default: 30) — The percentage of overlap between screenshot chunks. Defaults to 30 (percent). - `partitionDirection` (enum, optional, default: vertical) — 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. - Allowed values: `vertical`, `horizontal`, `bidirectional` - `resultSelectionStrategy` (enum, optional, default: 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. - Allowed values: `first`, `bestMatch`, `auto` - `scanScrollDelay` (long, optional, default: 1000) — Scan mode only: The delay between scrolls in milliseconds. Defaults to 1000 (milliseconds). - `scope` (enum, optional, default: 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. - Allowed values: `viewport`, `page`, `scan`, `auto` ### BrowserWaitNavigationConfig - `timeoutSeconds` (long, optional, default: 30) — The maximum time to wait for the navigation to complete, in seconds. Defaults to 30 (30 seconds). - `waitUntil` (enum, optional, default: load) — The condition to wait for the navigation to complete. Defaults to 'load'. - Allowed values: `load`, `domcontentloaded`, `networkidle0`, `networkidle2` ### ExternalSessionAiResponseMetadataUsage - `credits` (long, required) — The credit usage for this request - `id` (string, required) — The id of the request ### ClientProvidedResponseMetadata - `clientRequestId` (string, optional) ### ScreenshotMetadata - `dataUrl` (string, optional) — Base64 encoded data URL of screenshot image data - `fileId` (string, optional) — Unique identifier for the uploaded file - `fileName` (string, optional) — Name of the screenshot file - `format` (enum, optional) — Format of the screenshot data - Allowed values: `base64`, `url` - `scrollPosition` (ScreenshotScrollPosition, optional) — Scroll position where the screenshot was taken - `signedDownloadUrl` (string, optional) — Signed URL for downloading the screenshot (when format is 'url') - `urlExpiry` (string, optional) — Expiration time for the signed URL in ISO format - `viewportDimensions` (ScreenshotViewportDimensions, optional) — Viewport dimensions of the screenshot ### ScreenshotScrollPosition - `left` (long, required) — Horizontal scroll position in pixels - `top` (long, required) — Vertical scroll position in pixels ### ScreenshotViewportDimensions - `height` (long, required) — Height of the viewport in pixels - `width` (long, required) — Width of the viewport in pixels ## Examples **Request** ```json {} ``` **Response** ```json { "data": { "modelResponse": "modelResponse" }, "meta": { "status": "success", "usage": { "credits": 1000000, "id": "id" }, "clientProvided": { "clientRequestId": "clientRequestId" }, "requestId": "requestId", "screenshots": [ {} ] }, "errors": [ { "message": "message", "code": "code", "details": { "key": "value" }, "reason": "reason" } ], "warnings": [ { "message": "message", "code": "code", "details": { "key": "value" }, "reason": "reason" } ] } ``` **SDK Code** ```python import requests url = "https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/scroll" payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```typescript import { AirtopClient } from "@airtop/sdk"; const client = new AirtopClient({ apiKey: "YOUR_API_KEY" }); await client.windows.scroll("6aac6f73-bd89-4a76-ab32-5a6c422e8b0b", "0334da2a-91b0-42c5-6156-76a5eba87430"); ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/scroll" payload := strings.NewReader("{}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/scroll") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/scroll") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('POST', 'https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/scroll', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/scroll"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/scroll")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```