---
title: Screenshots API | TestingBot API Documentation
description: Generate cross-browser screenshots of any URL and retrieve the results
  through the TestingBot REST API.
source_url:
  html: https://testingbot.com/support/api/screenshots
  md: https://testingbot.com/support/api/screenshots.md
---

# Screenshots

Kick off a screenshot run across browsers and fetch the images when it finishes.

- **Endpoint:** api.testingbot.com
- **Version:** v1
- **Format:** JSON
- **Auth:** [HTTP Basic](https://testingbot.com/support/api#authentication)

POST `/v1/screenshots`

## Capture a new screenshot batch
 Queues a cross-browser screenshot of a given URL at a specified resolution. Rendering is asynchronous: this returns the batch ID only, so poll GET /v1/screenshots/:id until its `state` is `done` to collect the images. 
### Arguments

- **`url` string required:** Page URL to screenshot.
- **`resolution` string required:** Browser viewport (e.g. "1920x1080").
- **`browsers` array required:** Array of `{ browser, version, os }` triples (or `browser_id`s) to render with.
- **`wait_time` integer:** Seconds to wait after page load before snapping.
- **`fullpage` boolean:** Capture the entire scrollable page instead of just the viewport.
- **`callback_url` string:** POST callback URL invoked when the batch finishes processing.

POST `/v1/screenshots`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl -H 'Content-Type: application/json' -X POST "https://api.testingbot.com/v1/screenshots" \
-u key:secret \
-d '{
  "url": "https://www.google.com",
  "resolution": "1280x1024",
  "browsers": [
    { "browserName": "chrome", "version": 134, "os": "WIN10" },
    { "browserName": "safari", "version": "17.2", "platformName": "iOS", "deviceName": "iPhone 15" }
  ]
}'
```

```csharp
var client = new TestingBotClient(key, secret);
var batch = await client.Screenshots.CaptureAsync(new ScreenshotRequest
{
    Url = "https://www.google.com",
    Resolution = "1280x1024",
    BrowserIds = new[] { 1, 22 }
});
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.take_screenshots({ url: 'https://www.google.com', resolution: '1280x1024', browsers: [{ browserName: 'chrome', version: 134, os: 'WIN10' }] })
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.screenshots.take_screenshots('https://www.google.com', '1280x1024', [1, 22])
```

```php
$client = new TestingBot\Client($key, $secret);
$batch = $client->screenshots()->create('https://example.com', [1, 2], [
    'resolution' => '1920x1080',
]);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
Map<String, Object> params = new HashMap<>();
params.put("url", "https://www.google.com");
params.put("resolution", "1280x1024");
TestingbotScreenshot screenshots = restApi.createScreenshots(params);
```

```javascript
const TestingBot = require('testingbot-api');

const api = new TestingBot({
  api_key: "your-tb-key",
  api_secret: "your-tb-secret"
});

const screenshots = await api.takeScreenshot(
  'https://example.com',
  [{ browserName: 'chrome', version: 'latest', os: 'WIN11' }],
  '1920x1080'
);
```

Response

```json
{
  "id": 3454,
  "wait_time": 0,
  "resolution": "1280x1024",
  "url": "https://www.google.com"
}
```

GET `/v1/screenshots/{id}`

## Get screenshot batch detail
 Returns per-browser screenshot results for a single batch, including thumbnail/image URLs and processing state. 
### Arguments

- **`id` integer required:** Numeric screenshot batch ID.
- **`excludeIds` string:** Comma-separated screenshot IDs to exclude (useful for delta-fetch).

### Response fields

- **`id` integer:** Unique screenshot batch ID.
- **`url` string:** URL the screenshots were taken from.
- **`resolution` string:** Browser viewport resolution.
- **`state` string:** Batch state: `processing` until every browser has finished, then `done`.
- **`created_at` timestamp:** —
- **`screenshots` array of screenshot result objects:** Per-browser results with download URLs.

GET `/v1/screenshots/{id}`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/screenshots/{id}" -u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
var batch = await client.Screenshots.GetAsync(batchId);
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_screenshots(screenshot_id)
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.screenshots.get_screenshot(screenshot_id)
```

```php
$client = new TestingBot\Client($key, $secret);
$batch = $client->screenshots()->get($screenshotId);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotScreenshot screenshot = restApi.getScreenshot(screenshotId);
```

```javascript
const TestingBot = require('testingbot-api');

const api = new TestingBot({
  api_key: "your-tb-key",
  api_secret: "your-tb-secret"
});

const screenshotResult = await api.retrieveScreenshots(screenshotJobId);
```

Response

```json
{
  "id": 3454,
  "url": "https://www.google.com",
  "resolution": "1280x1024",
  "created_at": "2017-10-13T14:47:41.000Z",
  "state": "done",
  "screenshots": [
    {
      "image_url": "https://....",
      "thumb_url": "https://....",
      "state": "done",
      "id": "9c7deea4-6f23-4041-842b-39cccee447fa",
      "session_id": 0,
      "created_at": "2017-10-13T14:47:44.000Z",
      "os": "SEQUOIA",
      "browser_name": "googlechrome",
      "browser_version": "138",
      "browser_id": 1146,
      "device_name": null,
      "platform_name": null
    }
  ]
}
```

GET `/v1/screenshots`

## List screenshot batches
 Returns batches of cross-browser screenshots the account has queued historically. 
### Arguments

- **`offset` integer:** Skip this many batches.
- **`count` integer:** Number of batches to return.

### Response fields

- **`data` array of screenshot summary objects:** Screenshot batches for this page.
- **`meta` meta object:** —

GET `/v1/screenshots`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/screenshots" -u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
var history = await client.Screenshots.ListAsync();
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_screenshots_history(0, 10)
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.screenshots.get_screenshots(offset=0, limit=10)
```

```php
$client = new TestingBot\Client($key, $secret);
$batches = $client->screenshots()->list(0, 10);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotScreenshotCollection screenshots = restApi.getScreenshots();
```

```javascript
const TestingBot = require('testingbot-api');

const api = new TestingBot({
  api_key: "your-tb-key",
  api_secret: "your-tb-secret"
});

const screenshots = await api.getScreenshotList();
```

Response

```json
{
  "data": [
    { "id": 3454, "url": "https://google.com", "resolution": "1280x1024", "created_at": "2017-10-13T14:47:41.000Z" },
    { "id": 3452, "url": "https://testingbot.com", "resolution": "1280x1024", "created_at": "2017-10-12T09:22:03.000Z" }
  ],
  "meta": { "offset": 0, "count": 3, "total": 3 }
}
```

[Previous Insights](https://testingbot.com/support/api/insights) [Next Tunnel](https://testingbot.com/support/api/tunnel)