# 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.

**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.

```bash
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](https://thelastapi.dev/blog/scrape-website-to-markdown-api).

## 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:

```bash
# 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:

```bash
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](https://thelastapi.dev/docs/actions).

## 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 parameter | Type | Default | Accepted values | Purpose |
| --- | --- | --- | --- | --- |
| `url` | string | *required* | Any valid HTTP/HTTPS URL | The target address to load and capture. |
| `fullPage` | boolean | `false` | `true`, `false` | When `true`, scrolls the document to capture its entire vertical height. |
| `width` | integer | `1280` | `320` to `2560` | Sets 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:

```bash
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](https://thelastapi.dev/docs/design).

## 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.

```bash
npm install @vibiz/app
```

Then call `vibiz.actions.run` inside your code:

```ts
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](https://thelastapi.dev/blog/crawl-site-markdown-rag).

## Temporary links versus permanent file storage

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](https://thelastapi.dev/blog/deploy-website-from-claude-chatgpt).

## 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:

```bash
# 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](https://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.

---

Published 2026-11-15 · https://thelastapi.dev/blog/screenshot-webpage-api
