Get screenshot

Endpoint

GET https://api.screenshotly.dev/v1/screenshots/{screenshotId}

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key

Path parameters

screenshotId

string

required

The unique ID of the screenshot, returned by the capture endpoint when using response_type: "json".

Response

200 OK

{
  "success": true,
  "data": {
    "_id": "67b8a1c2d3e4f5a6b7c8d9e0",
    "userId": "67a1b2c3d4e5f6a7b8c9d0e1",
    "url": "https://example.com",
    "name": "Homepage screenshot",
    "status": "completed",
    "imageUrl": "https://cdn.screenshotly.dev/screenshots/67b8a1c2d3e4f5a6b7c8d9e0.png",
    "options": {
      "format": "png",
      "viewport_width": 1280,
      "viewport_height": 1024,
      "full_page": false,
      "device_scale_factor": 1,
      "image_quality": 80
    },
    "metadata": {
      "fileSize": 245760,
      "format": "png",
      "dimensions": {
        "width": 1280,
        "height": 1024
      }
    },
    "processingTime": 2340,
    "createdAt": "2025-05-14T10:00:00.000Z",
    "updatedAt": "2025-05-14T10:00:02.340Z"
  }
}

Response fields

success

boolean

Always true for successful requests.

data._id

string

The screenshot ID.

data.url

string

The original URL that was captured.

data.name

string

The screenshot name, if provided during capture.

data.status

string

Current status: "pending", "processing", "completed", or "failed".

data.imageUrl

string

URL to the captured screenshot image. Only present when status is "completed".

data.options

object

The capture options that were used for this screenshot.

data.metadata

object

File metadata including fileSize (bytes), format, and dimensions (width/height).

data.processingTime

number

Time taken to process the screenshot in milliseconds.

data.errorMessage

string

Error description if status is "failed".

data.createdAt

string

ISO 8601 timestamp of when the capture was requested.

data.updatedAt

string

ISO 8601 timestamp of the last status update.

Failed screenshot

{
  "success": true,
  "data": {
    "_id": "67b8a1c2d3e4f5a6b7c8d9e0",
    "url": "https://example.com",
    "status": "failed",
    "errorMessage": "Page navigation timed out.",
    "createdAt": "2025-05-14T10:00:00.000Z",
    "updatedAt": "2025-05-14T10:00:30.000Z"
  }
}

Error responses

Status	Code	Description
401	`missing_api_key` / `invalid_api_key`	Invalid or missing API key
403	`forbidden`	You don’t own this screenshot
404	`not_found`	Screenshot ID doesn’t exist

Polling for completion

If you’re not using webhooks, poll this endpoint to check when a screenshot is ready:

async function waitForScreenshot(screenshotId) {
  while (true) {
    const response = await fetch(
      `https://api.screenshotly.dev/v1/screenshots/${screenshotId}`,
      { headers: { 'X-API-Key': process.env.SCREENSHOTLY_API_KEY } }
    );
    const { data } = await response.json();

    if (data.status === 'completed') {
      return data.imageUrl;
    }

    if (data.status === 'failed') {
      throw new Error(data.errorMessage);
    }

    // Wait 1 second before checking again
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
}

For production use, prefer webhooks over polling. Webhooks are more efficient and reduce unnecessary API calls.

For a lightweight status check, use the screenshot status endpoint which returns only the id, status, and imageUrl.

Example

curl https://api.screenshotly.dev/v1/screenshots/67b8a1c2d3e4f5a6b7c8d9e0 \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY"

Overview

Capture

Screenshots

Resources

Endpoint

Headers

Path parameters

Response

200 OK

Response fields

Failed screenshot

Error responses

Polling for completion

Example

​Endpoint

​Headers

​Path parameters

​Response

​200 OK

​Response fields

​Failed screenshot

​Error responses

​Polling for completion

​Example

Endpoint

Headers

Path parameters

Response

200 OK

Response fields

Failed screenshot

Error responses

Polling for completion

Example