GoScreenAPI
Get started
REST API · v1

API Reference

Everything you need to integrate GoScreenAPI into your application. One endpoint, powerful options.

Authentication

Pass your API key via the Authorization header on every request.

HTTP Header 
Authorization: Bearer {{ $displayKey }}_here

Generate API keys from your dashboard. Each key can be revoked independently.

Endpoints

POST
https://goscreenapi.com/api/v1/screenshot

Create a screenshot request

GET
https://goscreenapi.com/api/v1/screenshot/{id}

Poll request status (async mode)

GET
https://goscreenapi.com/api/v1/screenshots

List your screenshot history (paginated)

GET
https://goscreenapi.com/api/v1/me

Get account info and quota status

Parameters

Send as JSON body with Content-Type: application/json.

Parameter Type Required Description
url string required* The URL to screenshot. Must be http/https. Required if html is not set.
html string optional Raw HTML string to render instead of a URL. Required if url is not set.
async boolean optional false = sync (wait for result, returns image_url directly). true = async (returns poll_url). Default: true.
device string optional desktop (default), mobile (390×844), or tablet (768×1024).
width integer optional Viewport width in px. Min: 100, Max: 4000.
height integer optional Viewport height in px. Min: 100, Max: 4000.
format string optional png (default), jpg, jpeg, webp, pdf.
quality integer optional JPEG/WebP quality 1-100. Default: 80.
full_page boolean optional Capture full scrollable page. Default: false.
block_ads boolean optional Block ad networks and trackers. Default: false.
block_cookies boolean optional Dismiss cookie consent banners. Default: false.
stealth boolean optional Enable stealth mode to bypass bot detection. Default: false.
delay integer optional Wait N milliseconds after page load before capture. Max: 10000.
timeout integer optional Page load timeout in ms. Min: 1000, Max: 60000. Default: 30000.
scroll_to integer optional Scroll to Y position (px) before capture.
proxy_country string optional ISO 3166-1 alpha-2 country code for IP routing (e.g. US, DE, TR).
js_scenario string optional JavaScript code to execute on the page before capture. Max 4096 chars.
selector string optional CSS selector — capture only the matching element (e.g. #hero, .card).
wait_for string optional CSS selector or ms to wait before capture (e.g. .loaded or 2000).
css string optional Custom CSS to inject into the page before capture. Max 65535 chars.
theme string optional light (default) or dark — sets prefers-color-scheme media query.
headers string optional JSON object of custom HTTP headers sent with the page request. Max 10 keys.
cache_ttl integer optional Cache result for N seconds (60–2592000). Same URL+params returns cached result.
webhook_url string optional URL to POST result to when screenshot completes (async mode).
webhook_secret string optional Secret for HMAC-SHA256 webhook signature verification.
signed_link boolean optional Generate a signed time-limited public link for the result.
signed_link_expires_in integer optional Signed link TTL in seconds. Min: 60, Max: 604800. Default: 3600.

* Either url or html is required.

Code Examples

cURL
curl -X POST 'https://goscreenapi.com/api/v1/screenshot' \
  -H 'Authorization: Bearer {{ $displayKey }}' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "full_page": true,
    "block_ads": true,
    "async": false
  }'
JavaScript
const response = await fetch('https://goscreenapi.com/api/v1/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{ $displayKey }}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    format: 'png',
    full_page: true,
    block_ads: true,
    async: false,
  }),
});

const data = await response.json();
console.log(data.image_url); // https://goscreenapi.com/storage/screenshots/uuid.png
PHP
$response = Http::withToken('{{ $displayKey }}')
    ->post('https://goscreenapi.com/api/v1/screenshot', [
        'url'       => 'https://example.com',
        'format'    => 'png',
        'full_page' => true,
        'block_ads' => true,
        'async'     => false,
    ]);

$data = $response->json();
echo $data['image_url'];
Python
import requests

response = requests.post(
    'https://goscreenapi.com/api/v1/screenshot',
    headers={'Authorization': 'Bearer {{ $displayKey }}'},
    json={
        'url': 'https://example.com',
        'format': 'png',
        'full_page': True,
        'block_ads': True,
        'async': False,
    }
)

data = response.json()
print(data['image_url'])

Response (sync mode — async: false)

JSON · 200 OK
{
  "status": "completed",
  "request_id": "018e1234-abcd-7000-8000-000000000001",
  "image_url": "https://goscreenapi.com/storage/screenshots/018e1234-abcd-7000-8000-000000000001.png",
  "duration_ms": 2984,
  "async": false,
  "quota": {
    "monthly_quota": 250,
    "monthly_used": 5,
    "monthly_remaining": 245,
    "overage_active": false
  }
}

Async Mode

Default mode. Request returns immediately with a poll_url. Poll until status is completed.

JSON · 202 Accepted
{
  "status": "queued",
  "request_id": "018e1234-abcd-7000-8000-000000000001",
  "poll_url": "https://goscreenapi.com/api/v1/screenshot/018e1234-abcd-7000-8000-000000000001",
  "async": true,
  "quota": { "monthly_quota": 250, "monthly_used": 4, "monthly_remaining": 246 }
}

Polling the result

cURL — Poll
curl 'https://goscreenapi.com/api/v1/screenshot/{request_id}' \
  -H 'Authorization: Bearer {{ $displayKey }}'

# Response when completed:
{
  "status": "success",
  "request": {
    "id": "018e1234-...",
    "status": "completed",
    "image_url": "https://goscreenapi.com/storage/screenshots/018e1234.png",
    "duration_ms": 3120,
    "requested_at": "2026-03-19T10:00:00Z",
    "completed_at": "2026-03-19T10:00:03Z"
  }
}

Advanced Example

Element screenshot with dark mode, custom CSS injection, and a custom auth header.

cURL — Advanced
curl -X POST 'https://goscreenapi.com/api/v1/screenshot' \
  -H 'Authorization: Bearer {{ $displayKey }}' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "selector": "#pricing-table",
    "theme": "dark",
    "wait_for": ".pricing-loaded",
    "css": ".cookie-banner { display: none; }",
    "headers": "{\"Authorization\": \"Bearer my_token\"}",
    "format": "png",
    "async": false
  }'
JavaScript — Advanced
const response = await fetch('https://goscreenapi.com/api/v1/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{ $displayKey }}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    selector: '#pricing-table',
    theme: 'dark',
    wait_for: '.pricing-loaded',
    css: '.cookie-banner { display: none; }',
    headers: JSON.stringify({ Authorization: 'Bearer my_token' }),
    format: 'png',
    async: false,
  }),
});
const data = await response.json();
console.log(data.image_url);
PHP — Advanced
$response = Http::withToken('{{ $displayKey }}')
    ->post('https://goscreenapi.com/api/v1/screenshot', [
        'url'      => 'https://example.com',
        'selector' => '#pricing-table',
        'theme'    => 'dark',
        'wait_for' => '.pricing-loaded',
        'css'      => '.cookie-banner { display: none; }',
        'headers'  => json_encode(['Authorization' => 'Bearer my_token']),
        'format'   => 'png',
        'async'    => false,
    ]);

echo $response->json('image_url');
Python — Advanced
import requests, json

response = requests.post(
    'https://goscreenapi.com/api/v1/screenshot',
    headers={'Authorization': 'Bearer {{ $displayKey }}'},
    json={
        'url': 'https://example.com',
        'selector': '#pricing-table',
        'theme': 'dark',
        'wait_for': '.pricing-loaded',
        'css': '.cookie-banner { display: none; }',
        'headers': json.dumps({'Authorization': 'Bearer my_token'}),
        'format': 'png',
        'async': False,
    }
)
print(response.json()['image_url'])

Account & Quota

GET /api/v1/me — Check your plan, quota usage, and wallet balance programmatically.

cURL
curl 'https://goscreenapi.com/api/v1/me' \
  -H 'Authorization: Bearer {{ $displayKey }}'
JSON · 200 OK
{
  "status": "success",
  "user": {
    "email": "[email]",
    "plan": "Pro",
    "overage_enabled": true,
    "wallet_balance": 12.50
  },
  "quota": {
    "monthly_quota": 5000,
    "monthly_used": 312,
    "monthly_remaining": 4688,
    "reset_at": "2026-04-01T00:00:00Z",
    "overage_active": false
  }
}

Screenshot History

GET /api/v1/screenshots — List your past requests. Supports ?status=completed and ?per_page=50 (max 100).

cURL
curl 'https://goscreenapi.com/api/v1/screenshots?per_page=10&status=completed' \
  -H 'Authorization: Bearer {{ $displayKey }}'
JSON · 200 OK
{
  "status": "success",
  "data": [
    {
      "id": "018e1234-...",
      "url": "https://example.com",
      "status": "completed",
      "format": "png",
      "device": "desktop",
      "image_url": "https://goscreenapi.com/storage/screenshots/018e1234.png",
      "duration_ms": 2984,
      "cache_hit": false,
      "requested_at": "2026-03-19T10:00:00Z",
      "completed_at": "2026-03-19T10:00:03Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 312,
    "last_page": 32
  }
}

Webhooks

Set webhook_url in your request. When the screenshot completes, we POST the result to your endpoint.

Signature verification: Each webhook includes an X-GSS-Signature header — HMAC-SHA256 of the raw body using your webhook_secret.
Webhook payload
{
  "request_id": "018e1234-...",
  "status": "completed",
  "image_url": "https://goscreenapi.com/storage/screenshots/018e1234.png",
  "duration_ms": 2984,
  "requested_at": "2026-03-19T10:00:00Z",
  "completed_at": "2026-03-19T10:00:03Z"
}

Error Codes

HTTP Meaning
401 Invalid or missing API key
403 Account suspended or inactive
422 Validation error — check errors field in response
429 Quota exceeded or too many pending requests
500 Internal server error
503 Worker temporarily unavailable

SSE Streaming

Real-time status updates for async requests via Server-Sent Events. Connect once and receive events as the screenshot progresses.

GET /api/v1/screenshot/{id}/stream
// JavaScript — EventSource
const es = new EventSource(
  'https://goscreenapi.com/api/v1/screenshot/{id}/stream?key=YOUR_KEY'
);

es.addEventListener('connected', e => console.log('Connected', JSON.parse(e.data)));
es.addEventListener('completed', e => {
  const data = JSON.parse(e.data);
  console.log('Done!', data.image_url);
  es.close();
});
es.addEventListener('heartbeat', e => console.log('Still processing...'));
es.addEventListener('timeout', e => { console.log('Timed out'); es.close(); });
Event When
connected Immediately on connection — confirms the request ID and current status
heartbeat Every 2 seconds while processing — keeps the connection alive
completed When screenshot finishes — includes image_url and duration_ms
failed If screenshot fails — includes error_message
timeout After 60 seconds if not completed — stream closes

Batch API

Submit up to 50 screenshot requests in a single call. All run in parallel on a dedicated queue. Learn more →

Submit a batch — POST /api/v1/batch

cURL
curl -X POST 'https://goscreenapi.com/api/v1/batch' \
  -H 'Authorization: Bearer {{ $displayKey }}' \
  -H 'Content-Type: application/json' \
  -d '{
    "callback_url": "https://yourapp.com/batch-done",
    "requests": [
      { "url": "https://stripe.com", "format": "png" },
      { "url": "https://github.com", "device": "mobile" },
      { "url": "https://vercel.com", "full_page": true }
    ]
  }'

// Response: 202 Accepted
{
  "status": "queued",
  "batch_id": "018e1234-abcd-...",
  "total_items": 3,
  "poll_url": "https://goscreenapi.com/api/v1/batch/018e1234-abcd-..."
}

Get batch status — GET /api/v1/batch/{id}

JSON · 200 OK
{
  "status": "success",
  "batch_id": "018e1234-...",
  "batch_status": "completed",
  "total_items": 3,
  "completed_items": 3,
  "failed_items": 0,
  "items": [
    {
      "request_id": "uuid-1",
      "url": "https://stripe.com",
      "status": "completed",
      "image_url": "https://cdn.goscreenapi.com/screenshots/uuid-1.png",
      "duration_ms": 1240
    }
  ]
}
Batch parameters: Each item in requests[] supports url, html, device, format, full_page, width, height, webhook_url. Max 50 items per batch.

Visual Diff API

Compare two screenshots pixel-by-pixel. Returns a diff percentage, pixel count, and a visual diff image. Results are cached — the same pair won't be recomputed. Learn more →

POST /api/v1/diff
curl -X POST 'https://goscreenapi.com/api/v1/diff' \
  -H 'Authorization: Bearer {{ $displayKey }}' \
  -H 'Content-Type: application/json' \
  -d '{
    "request_id_1": "uuid-before",
    "request_id_2": "uuid-after",
    "threshold": 0.1
  }'

// Response: 200 OK
{
  "status": "success",
  "diff_id": 42,
  "cached": false,
  "diff_percentage": 3.47,
  "diff_pixels": 12840,
  "compared_size": "1280x900",
  "threshold": 0.1,
  "diff_image": "data:image/png;base64,..."
}
Parameter Type Description
request_id_1 uuid ID of the first screenshot (must be completed)
request_id_2 uuid ID of the second screenshot (must be completed)
threshold float Sensitivity 0.0–1.0. Lower = more sensitive. Default: 0.1
force boolean true = recompute even if cached result exists

OG Image API

Generate dynamic Open Graph images (1200×630) from title, description, logo and colors. Returns a redirect to the image URL or a JSON response.

POST /api/v1/og-image
curl -X POST 'https://goscreenapi.com/api/v1/og-image' \
  -H 'Authorization: Bearer {{ $displayKey }}' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "My Article Title",
    "description": "A short description here",
    "theme": "dark",
    "bg_color": "#0f172a",
    "text_color": "#ffffff",
    "logo_url": "https://yoursite.com/logo.png",
    "redirect": false
  }'

// Response: 200 OK (redirect: false)
{
  "status": "success",
  "request_id": "uuid",
  "image_url": "https://cdn.goscreenapi.com/screenshots/uuid.png",
  "duration_ms": 1180
}
Parameter Description
title required — Main heading text. Max 150 chars.
description optional — Subtitle text. Max 300 chars.
theme optional — light or dark. Sets default bg/text colors.
bg_color optional — Background hex color (e.g. #0f172a).
text_color optional — Text hex color (e.g. #ffffff).
logo_url optional — URL of your logo image.
redirect optional — true (default) = redirect to image URL. false = JSON response.

Rate Limits

Each user can have at most 10 pending requests at a time. Monthly quota depends on your plan.

Need higher limits? Upgrade your plan or contact us for enterprise.

Embeddable Widgets

Create lightweight embed codes from your dashboard and paste them on any website. Each widget uses a secure, read-only token — your API key is never exposed.

Widget Type Embed Code Quota Usage Cache
Screenshot Widget <script src="…/widget/screenshot.js?t=TOKEN"></script> 1 screenshot per refresh interval 1h / 6h / 24h (configurable)
Uptime Badge <img src="…/widget/badge/TOKEN.svg"> 1 uptime check per 5 minutes 5 minutes
Status Page <iframe src="…/widget/status/TOKEN"></iframe> Free — no quota Real-time
Create and manage your widgets from the Widgets dashboard. Each widget tracks impressions and last usage time.