Page Analysis

The Page Analysis endpoint scans any webpage and returns a structured breakdown of its content: interactive elements, headings, forms, images, navigation links, and text blocks. Each element includes its bounding rectangle, so you can map every item to its exact position on the page.

Page Analysis is available as a Pro feature with unlimited requests. Free and Starter plans get 20 trial runs per month.

Endpoint

POST /v1/analyze

Send a JSON body with the target URL and options. The response is always JSON with two top-level keys: meta and result.

Request Parameters

Basic Example

curl -X POST https://api.screenshotrun.com/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "include": ["headings", "interactive", "images"]
  }'

$response = Http::withToken(env('SCREENSHOT_API_KEY'))
    ->timeout(60)
    ->post('https://api.screenshotrun.com/v1/analyze', [
        'url' => 'https://example.com',
        'include' => ['headings', 'interactive', 'images'],
    ]);

$data = $response->json();
$headings = $data['result']['headings'];
$images = $data['result']['images'];

const response = await fetch("https://api.screenshotrun.com/v1/analyze", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCREENSHOTRUN_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    include: ["headings", "interactive", "images"],
  }),
});

const { meta, result } = await response.json();
console.log(`Found ${result.headings.length} headings`);

import requests

response = requests.post(
    "https://api.screenshotrun.com/v1/analyze",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "url": "https://example.com",
        "include": ["headings", "interactive", "images"],
    },
    timeout=60,
)

data = response.json()
headings = data["result"]["headings"]
images = data["result"]["images"]

Response Format

The response contains two top-level objects: meta with request metadata and result with the analysis data.

Meta Object

Result Object

The result object contains the analyzed page data. Each category is an array of elements.

Bounding Rectangles

Every element includes a rect array with four values: [x, y, width, height] in pixels, measured from the top-left corner of the viewport. This lets you draw overlays, build visual maps, or calculate element positions relative to the page.

{
  "tag": "a",
  "text": "Sign Up",
  "href": "/register",
  "rect": [920, 24, 96, 40]
}

Full Response Example

{
  "meta": {
    "status": 200,
    "took": 2.4,
    "screenshot_url": null,
    "requests": 1,
    "trial": false,
    "tokens": 3200,
    "bytes": 12800
  },
  "result": {
    "url": "https://example.com",
    "page": {
      "title": "Example Domain",
      "description": "This domain is for use in illustrative examples.",
      "language": "en",
      "viewport": { "width": 1280, "height": 800 }
    },
    "headings": [
      { "level": 1, "text": "Example Domain", "rect": [200, 80, 880, 48] }
    ],
    "interactive": [
      { "tag": "a", "text": "More information...", "href": "https://www.iana.org/domains/example", "rect": [200, 160, 180, 20] }
    ],
    "forms": [],
    "images": [],
    "navigation": [],
    "stats": {
      "headings": 1,
      "interactive": 1,
      "forms": 0,
      "images": 0,
      "navigation": 0,
      "text": 2
    }
  }
}

Filtering with include

By default, the API returns all element categories. If you only need specific data, pass the include parameter to reduce the response size and speed up processing.

{
  "url": "https://example.com",
  "include": ["headings", "images"]
}

The response will only contain headings and images arrays. Other categories will be empty arrays.

Available categories:

Scoping to a Section

The scope parameter limits analysis to elements inside a specific CSS selector. This is useful for analyzing just the main content area, a sidebar, or a specific component.

{
  "url": "https://example.com",
  "scope": "main",
  "include": ["headings", "interactive"]
}

Only headings and interactive elements inside the <main> element will be returned. Header, footer, and sidebar content is excluded.

Analysis with Screenshot

Set with_screenshot: true to capture a viewport screenshot alongside the analysis. The screenshot URL is returned in meta.screenshot_url.

curl -X POST https://api.screenshotrun.com/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "with_screenshot": true,
    "width": 1440,
    "height": 900
  }'

Trial Limits

Page Analysis is a Pro feature. Non-Pro accounts (Free and Starter) get 20 trial analysis runs per calendar month. The counter resets on the 1st of each month.

When the trial limit is reached, the API returns a 402 error:

{
  "error": {
    "code": "TRIAL_LIMIT_REACHED",
    "message": "You have used all 20 trial analysis runs this month. Upgrade to Pro for unlimited access.",
    "status": 402
  }
}

Trial users can check remaining runs via the meta.left field in every successful response.

Error Responses

Use Cases

Page Analysis works well for a range of automation and monitoring tasks:

• SEO audits — check heading hierarchy, missing alt text, broken navigation structure
• Accessibility checks — find interactive elements without labels, images without alt attributes, forms missing field names
• Competitive analysis — map out a competitor's page structure, CTA placement, and navigation patterns
• Content monitoring — detect changes in page structure over time by comparing analysis snapshots
• AI agent input — feed structured page data to LLMs for reasoning about web content without sending full HTML
• Visual regression — combine with_screenshot and element positions to verify layout changes

Playground

You can try Page Analysis without writing code in the Playground. Switch to the Analysis tab, enter a URL, select the categories you want, and run the scan. The Playground shows the results in an interactive table with a visual map of element positions.

MCP Integration

If you use the ScreenshotRun MCP Server, your AI agent can run page analysis by calling the analyze_page tool. The MCP server passes the request to the same POST /v1/analyze endpoint documented here.

Next Steps

• Screenshots — capture website screenshots via the core API
• Screenshot Options — full parameter reference for all capture settings
• MCP Server — connect Page Analysis to AI agents
• Error Codes — complete error code reference