Skip to content
Docs

vercel httpstat

The vercel httpstat command is currently in beta. Features and behavior may change.

The vercel httpstat command works like httpstat, but automatically handles deployment protection bypass tokens for you. It provides visualization of HTTP timing statistics, showing how long each phase of an HTTP request takes. When your project has Deployment Protection enabled, this command lets you test protected deployments without manually managing bypass secrets.

The command runs the httpstat tool with the same arguments you provide, but adds an x-vercel-protection-bypass header with a valid token. This makes it simple to measure response times, analyze performance bottlenecks, or debug latency issues on protected deployments.

This command is available in Vercel CLI v48.9.0 and later. If you're using an older version, see Updating Vercel CLI.

Usage

terminal
vercel httpstat [path]

Using the vercel httpstat command to visualize HTTP timing statistics for a deployment.

Examples

Basic timing analysis

Get timing statistics for your production deployment:

terminal
vercel httpstat/api/hello

Getting timing statistics for the /api/hello endpoint on your production deployment.

POST request timing

Analyze timing for a POST request with JSON data. Use the -- separator to pass flags through to the underlying httpstat:

terminal
vercel httpstat/api/users---XPOST-H"Content-Type: application/json"-d'{"name":"John"}'

Measuring timing statistics for a POST request that creates a new user. The -- separator passes everything after it to httpstat.

Specific deployment timing

Test timing for a specific deployment by its URL:

terminal
vercel httpstat/api/status--deploymenthttps://my-app-abc123.vercel.app

Analyzing timing for a specific deployment instead of the production deployment.

Multiple requests

Run multiple requests to get average timing statistics by passing flags after --:

terminal
vercel httpstat/api/data---n10

Running 10 requests to get more reliable timing data.

How it works

When you run vercel httpstat:

  1. The CLI finds your linked project (or you can specify one with --scope)
  2. It gets the latest production deployment URL (or uses the deployment you specified)
  3. It retrieves or generates a deployment protection bypass token
  4. It runs the httpstat tool with the bypass token in the x-vercel-protection-bypass header
  5. The tool displays a visual breakdown of request timing phases: DNS lookup, TCP connection, TLS handshake, server processing, and content transfer

The command requires httpstat to be installed on your system.

Unique options

These are options that only apply to the vercel httpstat command. To pass flags through to the underlying httpstat command, place them after the -- separator.

Deployment

The --deployment option lets you specify a deployment ID or URL to request instead of using the production deployment.

terminal
vercel httpstat/api/hello--deploymenthttps://my-app-abc123.vercel.app

Using the --deployment option to target a specific deployment.

Protection bypass

The --protection-bypass option lets you provide your own deployment protection bypass secret instead of automatically generating one. This is useful when you already have a bypass secret configured.

terminal
vercel httpstat/api/hello--protection-bypassyour-secret-here

Using the --protection-bypass option with a manual secret.

You can also use the VERCEL_AUTOMATION_BYPASS_SECRET environment variable:

terminal
export VERCEL_AUTOMATION_BYPASS_SECRET=your-secret-herevercel httpstat/api/hello

Setting the bypass secret as an environment variable.

Yes

The --yes option, shorthand -y, skips the confirmation prompt when linking is required. Use it in non-interactive environments like CI.

terminal
vercel httpstat/api/hello--yes

Skipping the link confirmation prompt with --yes.

Understanding the output

The httpstat tool displays timing information in a visual format:

  • DNS Lookup: Time to resolve the domain name
  • TCP Connection: Time to establish a TCP connection
  • TLS Handshake: Time to complete the SSL/TLS handshake (for HTTPS)
  • Server Processing: Time for the server to generate the response
  • Content Transfer: Time to download the response body

Each phase is color-coded and displayed with its duration in milliseconds, helping you identify which part of the request is taking the most time.

Troubleshooting

httpstat command not found

Make sure httpstat is installed on your system:

terminal
# Install with pip (Python)pip installhttpstat# Or install with Homebrew (macOS)brew installhttpstat

Installing httpstat on different systems.

No deployment found for the project

Make sure you're in a directory with a linked Vercel project and that the project has at least one deployment:

terminal
# Link your projectvercel link# Deploy your projectvercel deploy

Linking your project and creating a deployment.

Failed to get deployment protection bypass token

If automatic token creation fails, you can create a bypass secret manually in the Vercel Dashboard:

  1. Go to your project's Settings → Deployment Protection
  2. Find "Protection Bypass for Automation"
  3. Click "Create" or "Generate" to create a new secret
  4. Copy the generated secret
  5. Use it with the --protection-bypass flag or VERCEL_AUTOMATION_BYPASS_SECRET environment variable

No deployment found for ID

When using --deployment, verify that:

  • The deployment ID or URL is correct
  • The deployment belongs to your linked project
  • The deployment hasn't been deleted

Global Options

The following global options can be passed when using the vercel httpstat command:

For more information on global options and their usage, refer to the options section.

Related

Last updated May 28, 2026
Previous
vercel help
Next
vercel init

Was this helpful?

supported.