---
title: "url parameter"
description: "Capture any public URL with the html2img Screenshot API. Authentication, redirects, timeouts."
url: "https://html2img.com/docs/parameters/url/"
---

# URL Parameter

The `url` parameter is required for the Screenshot API and specifies which webpage to capture.

## Specifications

| Property | Value |
|----------|-------|
| Type | string |
| Required | Yes |
| Default | None |
| API | Screenshot API only |

## Description

The URL of the webpage you want to screenshot. The URL must be:
- Publicly accessible
- A valid URL with protocol (http:// or https://)
- Responsive within a reasonable timeout period

> **Important**
>
> We strongly recommend using the `webhook_url` parameter with URL screenshots, as page load times can be unpredictable and may exceed the 30-second timeout limit.

## Examples

### Basic URL Screenshot
```json
{
    "url": "https://example.com"
}
```

Response:
```json
{
    "success": true,
    "id": "f90c7615-bbeb-47aa-bb69-ab643c90e36e",
    "expires_at": null,
    "credits_remaining": 950,
    "url": "https://i.html2img.com/image-1786092638463-130023.png"
}
```

### URL with Query Parameters
```json
{
    "url": "https://example.com/search?q=test&page=1"
}
```

### URL with Specific Viewport
```json
{
    "url": "https://example.com",
    "width": 1920,
    "height": 1080
}
```

> **Warning**
>
> Some websites block or behave differently when accessed by our service. Make sure the target website does not require authentication, allows automated access, and is publicly reachable.

## Common values

- `https://example.com/articles/123` - a public article page on a content site.
- `https://twitter.com/user/status/123` - a tweet permalink for screenshotting an embed.
- `https://your-app.com/invoices/42/preview` - a public preview page on your own site.
- `https://news.ycombinator.com/item?id=12345` - a discussion thread.

## When to use

Use the `url` parameter when the page already exists somewhere on the public web and you want a screenshot of it. For pages that need data injected, prefer the [html parameter](https://html2img.com/docs/parameters/html/) so you can build the markup at request time.

## Common mistakes

- **Pointing at a localhost or intranet URL.** The Screenshot API runs on our servers and cannot reach private hosts.
- **Forgetting redirects.** A URL that returns 301 or 302 follows the redirect, but a 401 or 403 returns an error. Make sure the page is reachable without auth.
- **Capturing pages with cookie banners.** Inject a hide selector via the [css parameter](https://html2img.com/docs/parameters/css/) before render.

See also: [twitter-embed example](https://html2img.com/docs/examples/twitter-embed/), [facebook-post example](https://html2img.com/docs/examples/facebook-post/), [instagram-post example](https://html2img.com/docs/examples/instagram-post/), [getting started guide](https://html2img.com/docs/getting-started/).

## Templates that use this parameter

Templates that render external URLs as part of their input pipeline:

- [Tweet mockup card template](https://html2img.com/templates/tweet-mockup-card/)
- [GitHub social preview template](https://html2img.com/templates/github-social-preview/)