thelastapi
Get started free

Screenshot a web page with an API

Capture full-page or viewport website screenshots using a single API call, CLI command, or SDK method that returns clean PNG image URLs.

On this page 8 sections

You can screenshot any public web page by sending its URL to the web.screenshot action over HTTP, the CLI, or the SDK. thelastapi renders the target address in a headless browser, captures the viewport or the full document, and returns the image link along with page metadata. When called inside a project, the resulting screenshot is automatically stored in your project's Files with a permanent link.

Whether you are generating preview cards, monitoring visual changes, archiving pages, or handing visual context to AI agents, here is how to capture website screenshots programmatically.

How to take a screenshot with curl

To capture a page using plain HTTP, make a POST request to /v1/actions/web.screenshot. You pass your API key in the authorization header and specify the target URL inside the input object.

Terminal
curl https://thelastapi.dev/v1/actions/web.screenshot \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://example.com"
    }
  }'

The response includes the captured title, dimensions, and the image payload:

JSON
{
  "object": "action_result",
  "action": "web.screenshot",
  "output": {
    "url": "https://example.com",
    "title": "Example Domain",
    "image": {
      "url": "https://thelastapi.dev/files/prj_123/web-data/shot_abc.png",
      "expires_at": "2026-04-01T12:00:00Z"
    },
    "fullPage": false,
    "width": 1280,
    "file_id": "file_abc123",
    "file_url": "https://thelastapi.dev/files/prj_123/web-data/shot_abc.png"
  },
  "cost_micro_usd": 800,
  "run_id": "arun_xyz789",
  "console_url": "https://thelastapi.dev/web-data?action=web.screenshot&run=arun_xyz789"
}

Every response returns cost_micro_usd so you can monitor your spend down to the microdollar on each run. If you need clean text instead of an image, see how to scrape a website to markdown with one API call.

How to capture screenshots from the CLI

When testing locally, debugging, or writing shell scripts, the vibiz CLI provides a direct way to trigger screenshots without writing boilerplate code.

Use vibiz run web.screenshot with an inline JSON payload:

Terminal
# Capture the default viewport (1280px width)
vibiz run web.screenshot --input '{"url":"https://example.com"}'

# Capture the entire scrolling height of the page
vibiz run web.screenshot --input '{"url":"https://example.com","fullPage":true}'

# Emulate a mobile or tablet viewport width
vibiz run web.screenshot --input '{"url":"https://example.com","width":375}'

To review past requests and see outputs from earlier executions, inspect your run history directly in your terminal:

Terminal
vibiz runs --action web.screenshot --since 1d
vibiz runs arun_xyz789

You can read more about running actions and checking logs in the Web data docs.

Capturing full-page versus above-the-fold views

By default, the screenshot engine captures an above-the-fold image using a standard desktop browser viewport width of 1280 pixels. Depending on your use case, you can adjust two optional parameters:

Input parameterTypeDefaultAccepted valuesPurpose
urlstringrequiredAny valid HTTP/HTTPS URLThe target address to load and capture.
fullPagebooleanfalsetrue, falseWhen true, scrolls the document to capture its entire vertical height.
widthinteger1280320 to 2560Sets the viewport width in pixels to test mobile, tablet, or large desktop layouts.

For social media preview cards or thumbnail generators, the default standard viewport (fullPage: false) avoids unusually tall images. For legal archiving, compliance reviews, or full visual audits, set "fullPage": true so footer navigation, pricing tables, and lower sections are preserved.

Here is a full-page capture request sent over HTTP:

Terminal
curl https://thelastapi.dev/v1/actions/web.screenshot \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://example.com",
      "fullPage": true,
      "width": 1440
    }
  }'

If you are inspecting a layout rather than just capturing an image, you can also learn a site's structure, tokens, and components using the Design documentation.

Using the TypeScript SDK in your application

When building web applications, backend services, or background workers, you can execute screenshots using @vibiz/app. The SDK manages authentication automatically via the VIBIZ_APP_KEY environment variable.

Terminal
npm install @vibiz/app

Then call vibiz.actions.run inside your code:

TypeScript
import { vibiz } from '@vibiz/app';

interface ScreenshotResult {
  url: string;
  title: string;
  image: {
    url: string;
    expires_at: string;
  };
  fullPage: boolean;
  width: number;
  file_id?: string;
  file_url?: string;
}

async function captureLandingPage(targetUrl: string) {
  const result = await vibiz.actions.run('web.screenshot', {
    url: targetUrl,
    fullPage: true,
    width: 1280,
  });

  const output = result.output as ScreenshotResult;

  console.log(`Captured title: ${output.title}`);
  console.log(`Image link: ${output.image.url}`);

  if (output.file_url) {
    console.log(`Saved permanently in project Files: ${output.file_url}`);
  }

  return output;
}

captureLandingPage('https://example.com');

When building autonomous bots or tools, agents can also call the screenshot action using the vibiz_run_action tool with the argument { name: "web.screenshot", input: { url: "https://example.com" } }. If you are assembling broader knowledge bases, you might also want to crawl a whole site to markdown for RAG.

Where your screenshot image is hosted depends on how you run the call:

  1. Inside a project scope: When you pass a project context (either using an app key from vibiz dev, targeting /v1/projects/:id/actions/web.screenshot, or using @vibiz/app in an active project), the screenshot is automatically written into the project's permanent file store inside the web-data folder. The returned image.url and file_url are durable, permanent links.
  2. Without a project scope: When calling the top-level account endpoint /v1/actions/web.screenshot using an account-level API key, no permanent file record is attached. The returned image.url points to an image with a signed lifespan, valid for one day (expires_at).

If you are building a user-facing dashboard or storing assets for public display, execute the action within a project so your links do not expire. If you need to deploy an entire web app without touching server setup, review how to deploy a website from Claude or ChatGPT with nothing installed.

Understanding pricing and spend ceilings

The screenshot action is billed based on actual resource consumption plus the platform's standard 30% web data margin.

A single page screenshot typically costs a fraction of a cent (around $0.0008 before margin). Every completed request includes cost_micro_usd in its JSON payload, reflecting the exact raw infrastructure cost in microdollars.

All screenshot usage draws against your account's credits and is governed by your account daily ceiling ($5 per day by default) as well as any individual project daily budgets ($1 per day by default). If your project or account hits its limit, calls return a 429 rate_limited status with a reason in the error response.

You can inspect accumulated spend and billing numbers across your web actions at any time:

Terminal
# Check current account usage and billed totals
vibiz usage

Handling common errors

The screenshot endpoint validates inputs strictly before attempting to open the remote address. Here are the common error codes and how to handle them:

  • 400 invalid_request: The provided url is missing, malformed, or the width is outside the accepted boundary of 320 to 2560 pixels. The details.field property specifies which parameter caused the error.
  • 402 payment_required: Your account has run out of prepaid credits. Add credits using vibiz billing top-up or through the console.
  • 429 rate_limited: You have reached the project daily budget or the account-level daily spend ceiling. Wait until midnight UTC or raise your daily ceiling in Billing settings.
  • 503 provider_unavailable: The destination server took too long to respond, or the page rendering process timed out. If details.reason is "timeout", check if the destination site is reachable or try capturing with a narrower width.

To get started, try capturing your first page from the CLI or create your account at thelastapi.dev/start.

Frequently asked questions

What image format does the website screenshot API return?

The action captures and returns the page rendering as a PNG image, accessible via the `image.url` field in the response.

How long do screenshot URLs stay active?

When executed within a project, the screenshot is saved to your project's Files under the `web-data` folder and receives a permanent link. When executed without a project, the link is valid for 24 hours.

What viewport widths can I specify?

You can set any viewport width between 320 pixels and 2560 pixels using the `width` parameter, with 1280 pixels used as the default.

Can an AI agent take screenshots using this API?

Yes. Agents can execute the `web.screenshot` action directly through MCP tools using `vibiz_run_action` with `name: "web.screenshot"` and the target URL in the input object.