vercel billing usage

The vercel billing usage command displays billing usage for the current billing period or a custom date range. It shows usage and costs for each service, helping you understand your resource consumption.

This is only available for Owner, Member, Developer, Security, Billing, and Enterprise Viewer roles for the current active team.

The command is available in vercel@65.11.0 and later, where the old name, vercel usage, still works but prints a deprecation warning. Use vercel billing usage in new scripts.

vercel billing usage

vercel billing usage --since 2025-01-01 --until 2025-01-31

The command outputs separate tables for infrastructure usage and subscription licenses. Each table shows:

• Service: The name of each Vercel service
• Usage: The quantity used, in the service's unit
• Cost: The cost accrued before credits and discounts, in USD or legacy MIUs. It isn't the amount on your invoice.

These are options that only apply to the vercel billing usage command.

The --since option, shorthand -s, specifies the start of the usage query. It accepts a YYYY-MM-DD date, an ISO 8601 timestamp, or a relative duration such as 7d. Date-only values start at midnight in Los Angeles (Pacific) time. Relative durations count backward from now.

vercel billing usage --since 7d

When you provide --since alone, the end defaults to now. Omit both time options to query the current billing period.

The --until option, shorthand -u, specifies the end of the usage query. It accepts the same formats as --since. A date-only value includes the full day in Los Angeles (Pacific) time, ending at the next midnight.

vercel billing usage --since 2025-01-01 --until 2025-01-31

When using --until, you must also specify --since.

--from and --to remain supported, but print a deprecation warning. Use --since and --until for new commands.

The --breakdown option shows usage grouped by time period instead of aggregated totals. Valid values are daily, weekly, or monthly.

vercel billing usage --breakdown daily

vercel billing usage --since 2025-01-01 --until 2025-01-31 --breakdown weekly

When using the breakdown mode, the output shows:

• Usage grouped by the specified period (day, week, or month)
• Per-service details for each period
• The total cost for each period

The data supports 1-day granularity with a maximum date range of 1 year.

The --group-by option shows usage grouped by a dimension instead of aggregated totals. Valid values are project and region. You can't combine --group-by with --breakdown.

vercel billing usage --group-by project

The --json option prints the usage data as a single JSON object on stdout instead of a table. --format json still works but is deprecated.

vercel billing usage --json

The JSON output includes:

• period: The start and end of the query
• context: The account or team name
• costUnit: USD or managed_infrastructure_units, for every cost in the output
• services: An array of services with usage and cost details
• totals: Aggregated totals for all services
• creditBalance: The current credit balance, when available. It's omitted for custom date ranges

When using --breakdown, the JSON output includes a breakdown object with the usage for each period. When using --group-by, it includes a groupBy object with the usage for each project or region.

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

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --non-interactive
• --scope
• --token
• --version

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