> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenshotly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get screenshot

> GET /v1/screenshots/{screenshotId} — retrieve the status and details of a screenshot.

## Endpoint

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

## Headers

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

## Path parameters

<ParamField path="screenshotId" type="string" required>
  The unique ID of the screenshot, returned by the [capture endpoint](/api-reference/capture-screenshot) when using `response_type: "json"`.
</ParamField>

## Response

### 200 OK

```json theme={null}
{
  "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

<ResponseField name="success" type="boolean">
  Always `true` for successful requests.
</ResponseField>

<ResponseField name="data._id" type="string">
  The screenshot ID.
</ResponseField>

<ResponseField name="data.url" type="string">
  The original URL that was captured.
</ResponseField>

<ResponseField name="data.name" type="string">
  The screenshot name, if provided during capture.
</ResponseField>

<ResponseField name="data.status" type="string">
  Current status: `"pending"`, `"processing"`, `"completed"`, or `"failed"`.
</ResponseField>

<ResponseField name="data.imageUrl" type="string">
  URL to the captured screenshot image. Only present when `status` is `"completed"`.
</ResponseField>

<ResponseField name="data.options" type="object">
  The capture options that were used for this screenshot.
</ResponseField>

<ResponseField name="data.metadata" type="object">
  File metadata including `fileSize` (bytes), `format`, and `dimensions` (width/height).
</ResponseField>

<ResponseField name="data.processingTime" type="number">
  Time taken to process the screenshot in milliseconds.
</ResponseField>

<ResponseField name="data.errorMessage" type="string">
  Error description if `status` is `"failed"`.
</ResponseField>

<ResponseField name="data.createdAt" type="string">
  ISO 8601 timestamp of when the capture was requested.
</ResponseField>

<ResponseField name="data.updatedAt" type="string">
  ISO 8601 timestamp of the last status update.
</ResponseField>

### Failed screenshot

```json theme={null}
{
  "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](/guides/webhooks), poll this endpoint to check when a screenshot is ready:

```javascript theme={null}
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));
  }
}
```

<Tip>
  For production use, prefer [webhooks](/guides/webhooks) over polling. Webhooks are more efficient and reduce unnecessary API calls.
</Tip>

<Tip>
  For a lightweight status check, use the [screenshot status endpoint](/api-reference/screenshot-status) which returns only the `id`, `status`, and `imageUrl`.
</Tip>

## Example

```bash theme={null}
curl https://api.screenshotly.dev/v1/screenshots/67b8a1c2d3e4f5a6b7c8d9e0 \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY"
```