Skip to main content

​
Endpoint

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

​
Headers

HeaderRequiredDescription
X-API-KeyYesYour 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

StatusCodeDescription
401missing_api_key / invalid_api_keyInvalid or missing API key
403forbiddenYou don’t own this screenshot
404not_foundScreenshot 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"