railway usage

Inspect workspace and project costs for a billing period, and manage compute and agent usage limits.

Usage

Run railway usage without a subcommand for a workspace summary.

railway usage [OPTIONS] [COMMAND]

Command	Description
`projects`	Show project-level or service-level usage
`limit`	Show or change compute and agent usage limits

Select a workspace

Pass --workspace with a workspace name or ID to select it explicitly.

railway usage --workspace Acme

Without this flag, the CLI uses the workspace that owns the linked project. If the directory isn't linked, it uses your only workspace or prompts you to choose one. Non-interactive sessions with multiple workspaces must pass --workspace.

Inspect workspace usage

The workspace summary shows the billing period, current usage, current bill, estimated bill, resource line items, and compute usage limits.

railway usage
railway usage --period previous
railway usage --period 2026-07 --json

Flag	Description
`--workspace <WORKSPACE>`	Workspace name or ID
`--period <PERIOD>`	`current`, `previous`, or `YYYY-MM`. Defaults to `current`
`--json`	Output in JSON format

Historical usage is available for the last 90 days. The CLI rejects future billing periods. Estimated bill and usage-limit fields apply to the current period.

Inspect usage by project

Use usage projects to rank projects by cost for the selected billing period.

railway usage projects
railway usage projects --limit 10

Human-readable output shows the top 25 projects by default and combines the remainder into an "Other projects" row. JSON output returns every project unless you pass --limit.

Flag	Description
`--project <PROJECT>`	Show a service-level breakdown for one project name or ID
`--period <PERIOD>`	`current`, `previous`, or `YYYY-MM`
`--limit <COUNT>`	Maximum projects to return. Can't be combined with `--project`
`--workspace <WORKSPACE>`	Workspace name or ID
`--json`	Output in JSON format

Select one project to show its CPU, memory, egress, volume, backup, and total cost by service:

railway usage projects --project api --period previous

Inspect usage limits

Usage limits track compute and Railway Agent spend independently. Without a target, the status command shows both.

railway usage limit status
railway usage limit status --target workspace
railway usage limit status --target agent

The --target values are workspace for compute usage and agent for Railway Agent usage.

Set workspace compute limits

Set a custom email alert, a hard limit, or both for compute usage. Workspace amounts must use whole dollars.

railway usage limit set \
  --target workspace \
  --soft 75 \
  --hard 125

Flag	Description
`--target workspace`	Required target for `set`
`--soft <DOLLARS>`	Email alert. Use `0` or a whole-dollar value from `$5` to `$500,000`
`--hard <DOLLARS>`	Hard limit. Use `0` or a whole-dollar value from `$10` to `$500,000`

The hard limit must be greater than or equal to the email alert when both are non-zero. Omitted values preserve an existing threshold.

The update command is a compatibility shortcut for workspace compute limits:

railway usage limit update --soft 100

Remove workspace compute limits with confirmation:

railway usage limit remove
railway usage limit remove --yes

Non-interactive sessions must pass --yes to remove a compute limit.

Set agent usage limits

Agent limits accept dollar amounts with up to two decimal places. A hard limit is required because agent usage limits can't be removed.

railway usage limit set \
  --target agent \
  --soft 7.50 \
  --hard 20

Flag	Description
`--target agent`	Required target for `set`
`--soft <DOLLARS>`	Optional email alert with cent-level precision
`--hard <DOLLARS>`	Required hard limit with cent-level precision

The hard limit must be greater than or equal to the email alert and can't exceed $500,000. Set --hard 0 to block additional agent usage.

Use commands in automation

Pass --json to summaries, project breakdowns, and limit commands for stable machine-readable output. JSON mode doesn't print progress spinners.

The --period flag applies only to usage summaries and project breakdowns. It isn't accepted by usage limit commands.

These pages explain usage reporting, limits, and Railway plans.