Manage Screenshots API

Retrieve, list, and delete your screenshots. Check processing status, download URLs, and manage your screenshot library with filtering, pagination, and search capabilities.

GET

/v1/screenshots/:id

Retrieve detailed information about a specific screenshot, including its status, download URL, and processing metrics.

Base URL: https://www.snapshotai.dev

Download URL

The download_url is a signed URL that expires in 1 hour. Generate a new one by calling this endpoint again if needed.

Path Parameters

idstringRequired

The unique identifier of the screenshot (starts with scr_)

Examples

cURL•bash

curl -X GET https://www.snapshotai.dev/api/v1/screenshots/scr_2nX8Kp9mJ4dL7qR \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript•javascript

const response = await fetch(
  'https://www.snapshotai.dev/api/v1/screenshots/scr_2nX8Kp9mJ4dL7qR',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const screenshot = await response.json();

if (screenshot.status === 'completed') {
  console.log('Download URL:', screenshot.download_url);
  console.log('File size:', screenshot.file_size_bytes, 'bytes');
  console.log('Processing time:', screenshot.processing_duration_ms, 'ms');
}

Success Response

200 OKapplication/json

{
  "id": "scr_2nX8Kp9mJ4dL7qR",
  "url_to_capture": "https://example.com",
  "status": "completed",
  "options": {
    "viewport_width": 1920,
    "viewport_height": 1080,
    "format": "png",
    "full_page": true
  },
  "storage_path": "users/usr_abc123/scr_2nX8Kp9mJ4dL7qR.png",
  "file_size_bytes": 245678,
  "processing_duration_ms": 3420,
  "download_url": "https://storage.snapshotai.dev/screenshots/users/usr_abc123/scr_2nX8Kp9mJ4dL7qR.png?token=...",
  "created_at": "2025-11-04T23:30:15.123Z",
  "processing_started_at": "2025-11-04T23:30:16.234Z",
  "completed_at": "2025-11-04T23:30:19.654Z",
  "error_message": null
}

Status Values

• pending - Job queued, waiting to start
• processing - Currently capturing screenshot
• completed - Screenshot ready, download_url available
• failed - Error occurred, check error_message

GET

/v1/screenshots

List all your screenshots with filtering, searching, and pagination support. Results are sorted by creation date (newest first).

Base URL: https://www.snapshotai.dev

Query Parameters

pagenumberOptional

Page number for pagination

Default: 1

Example: 2

limitnumberOptional

Number of results per page (max 100)

Default: 20

Example: 50

statusenumOptional

Filter by status: pending, processing, completed, failed

Example: completed

from_datestringOptional

Filter screenshots created after this date (ISO 8601)

Example: 2025-01-01T00:00:00Z

to_datestringOptional

Filter screenshots created before this date (ISO 8601)

Example: 2025-12-31T23:59:59Z

searchstringOptional

Search by URL (partial match, case-insensitive)

Example: example.com

Examples

cURL•bash

curl -X GET "https://www.snapshotai.dev/api/v1/screenshots?page=1&limit=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python•python

import requests

url = "https://www.snapshotai.dev/api/v1/screenshots"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {
    "page": 1,
    "limit": 20,
    "status": "completed"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

for screenshot in data['data']:
    print(f"{screenshot['id']}: {screenshot['url_to_capture']} - {screenshot['status']}")

print(f"Total: {data['meta']['total']} screenshots")

Success Response

200 OKapplication/json

{
  "data": [
    {
      "id": "scr_2nX8Kp9mJ4dL7qR",
      "url_to_capture": "https://example.com",
      "status": "completed",
      "options": {
        "viewport_width": 1920,
        "viewport_height": 1080,
        "format": "png"
      },
      "storage_path": "users/usr_abc123/scr_2nX8Kp9mJ4dL7qR.png",
      "file_size_bytes": 245678,
      "processing_duration_ms": 3420,
      "created_at": "2025-11-04T23:30:15.123Z",
      "completed_at": "2025-11-04T23:30:19.654Z"
    },
    {
      "id": "scr_9pK2mN8xJ7fH3wQ",
      "url_to_capture": "https://another-example.com",
      "status": "pending",
      "options": {
        "viewport_width": 1280,
        "viewport_height": 720,
        "format": "jpeg"
      },
      "storage_path": null,
      "file_size_bytes": null,
      "processing_duration_ms": null,
      "created_at": "2025-11-04T23:35:10.456Z",
      "completed_at": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "pages": 3
  }
}

Pagination

Use the meta object to implement pagination. The total field shows total screenshots matching your filters.

DELETE

/v1/screenshots/:id

Permanently delete a screenshot and remove its file from storage. This action cannot be undone.

Base URL: https://www.snapshotai.dev

Permanent Deletion

This action permanently deletes the screenshot record and its file from storage. You cannot recover deleted screenshots.

Path Parameters

idstringRequired

The unique identifier of the screenshot to delete

Example

cURL•bash

curl -X DELETE https://www.snapshotai.dev/api/v1/screenshots/scr_2nX8Kp9mJ4dL7qR \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

204 No Content

Empty response body. Screenshot successfully deleted.

const response = await fetch( 'https://www.snapshotai.dev/api/v1/screenshots/scr_2nX8Kp9mJ4dL7qR', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const screenshot = await response.json(); if (screenshot.status === 'completed') { console.log('Download URL:', screenshot.download_url); console.log('File size:', screenshot.file_size_bytes, 'bytes'); console.log('Processing time:', screenshot.processing_duration_ms, 'ms'); }

{ "id": "scr_2nX8Kp9mJ4dL7qR", "url_to_capture": "https://example.com", "status": "completed", "options": { "viewport_width": 1920, "viewport_height": 1080, "format": "png", "full_page": true }, "storage_path": "users/usr_abc123/scr_2nX8Kp9mJ4dL7qR.png", "file_size_bytes": 245678, "processing_duration_ms": 3420, "download_url": "https://storage.snapshotai.dev/screenshots/users/usr_abc123/scr_2nX8Kp9mJ4dL7qR.png?token=...", "created_at": "2025-11-04T23:30:15.123Z", "processing_started_at": "2025-11-04T23:30:16.234Z", "completed_at": "2025-11-04T23:30:19.654Z", "error_message": null }

import requests url = "https://www.snapshotai.dev/api/v1/screenshots" headers = {"Authorization": "Bearer YOUR_API_KEY"} params = { "page": 1, "limit": 20, "status": "completed" } response = requests.get(url, headers=headers, params=params) data = response.json() for screenshot in data['data']: print(f"{screenshot['id']}: {screenshot['url_to_capture']} - {screenshot['status']}") print(f"Total: {data['meta']['total']} screenshots")

{ "data": [ { "id": "scr_2nX8Kp9mJ4dL7qR", "url_to_capture": "https://example.com", "status": "completed", "options": { "viewport_width": 1920, "viewport_height": 1080, "format": "png" }, "storage_path": "users/usr_abc123/scr_2nX8Kp9mJ4dL7qR.png", "file_size_bytes": 245678, "processing_duration_ms": 3420, "created_at": "2025-11-04T23:30:15.123Z", "completed_at": "2025-11-04T23:30:19.654Z" }, { "id": "scr_9pK2mN8xJ7fH3wQ", "url_to_capture": "https://another-example.com", "status": "pending", "options": { "viewport_width": 1280, "viewport_height": 720, "format": "jpeg" }, "storage_path": null, "file_size_bytes": null, "processing_duration_ms": null, "created_at": "2025-11-04T23:35:10.456Z", "completed_at": null } ], "meta": { "page": 1, "limit": 20, "total": 47, "pages": 3 } }