Get screenshot

Endpoint

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

Headers

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

Path parameters

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

boolean

Always true for successful requests.

string

The screenshot ID.

string

The original URL that was captured.

string

The screenshot name, if provided during capture.

string

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

string

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

object

The capture options that were used for this screenshot.

object

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

number

Time taken to process the screenshot in milliseconds.

string

Error description if status is "failed".

string

ISO 8601 timestamp of when the capture was requested.

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