> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# baseten route

> Manage routes (PRE-RELEASE)

<Note>
  PRE-RELEASE: route commands are not GA yet. Their arguments, flags, and output may change.
</Note>

Manage routes. Baseten derives each route's name from its target. A route's name, team, and target cannot be changed after creation.

## list

```sh theme={"system"}
baseten route list [OPTIONS]
```

List all routes you can invoke, newest first.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID to scope the listing to. Defaults to all routes you can invoke.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List all visible routes

```sh theme={"system"}
baseten route list
```

Filter by team

```sh theme={"system"}
baseten route list --team Engineering
```

### Filter output with `--jq`

Print route names

```sh theme={"system"}
baseten route list --jq '.items[].name'
```

### Output

**Text mode (`--output text`):** Table with columns: ID, NAME, DISPLAY NAME, TEAM, TARGET, CREATED. When no routes match, prints "No routes found." to stderr.

**JSON mode (`--output json`):** payload type `cmd.RouteList`.

All matching routes in items. target.type is BASETEN\_MODEL\_API, ANTHROPIC, OPENAI, or XAI. Every target includes model. External targets also include secret\_name.

## describe

```sh theme={"system"}
baseten route describe [OPTIONS]
```

Describe a route by ID or exact name. Pass exactly one of `--id` or `--name`.

### Options

<ParamField body="--id" type="TEXT">
  Stable route ID.

  Mutually exclusive with other flags in group `route-ref`.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--name" type="TEXT">
  Exact route name, including its organization-owned prefix.

  Mutually exclusive with other flags in group `route-ref`.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Describe a route by name

```sh theme={"system"}
baseten route describe --name acme/assistant
```

### Filter output with `--jq`

Print the invoke URL

```sh theme={"system"}
baseten route describe --id <id> --jq '.invoke_url'
```

### Output

**Text mode (`--output text`):** Field-per-line summary of the route, including its target, invoke URL, and team name. Unrecognized target types are shown as `<unrecognized type>`.

**JSON mode (`--output json`):** payload type `managementapi.Route`.

target.type is BASETEN\_MODEL\_API, ANTHROPIC, OPENAI, or XAI. Every target includes model. External targets also include secret\_name.

## create

```sh theme={"system"}
baseten route create [OPTIONS]
```

Create a route with `--target-type` and `--target-model`. Baseten derives the route's name from its target. Find Model API names with `baseten model-api list`.

Omit `--team` to use the organization's default team. External targets require `--target-secret`, the name of an existing secret in the route's team. Store credentials in a secret with `baseten org secret set --name <secret-name>`; pass the same `--team` value if the route uses a specific team.

Set optional metadata with `--display-name` and `--description`.

### Options

<ParamField body="--description" type="TEXT">
  Optional route description (up to 1000 characters).
</ParamField>

<ParamField body="--display-name" type="TEXT">
  Display name (1 to 255 characters). Defaults to the route name.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--target-model" type="TEXT" required>
  Model API name or external provider model name.
</ParamField>

<ParamField body="--target-secret" type="TEXT">
  Name of an existing secret in the route's team. Required for external targets.
</ParamField>

<ParamField body="--target-type" type="TEXT" required>
  Target type.

  One of: `baseten-model-api`, `anthropic`, `openai`, `xai`
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID the route belongs to. Defaults to the organization's default team. Run 'baseten org team list' to see teams.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Create a Model API route

```sh theme={"system"}
baseten route create --target-type baseten-model-api --target-model <model>
```

Create an external provider route

```sh theme={"system"}
baseten route create --target-type anthropic --target-model <model> --target-secret anthropic-key
```

### Filter output with `--jq`

Print the created route ID

```sh theme={"system"}
baseten route create --target-type baseten-model-api --target-model <model> --jq '.id'
```

### Output

**Text mode (`--output text`):** On success, prints "Created route `name` (`id`)" to stderr; no stdout output.

**JSON mode (`--output json`):** payload type `managementapi.Route`.

target.type is BASETEN\_MODEL\_API, ANTHROPIC, OPENAI, or XAI. Every target includes model. External targets also include secret\_name.

## update

```sh theme={"system"}
baseten route update [OPTIONS]
```

Update a route by ID or exact name. Pass exactly one of `--id` or `--name`.

Pass `--display-name` or `--description`; omitted fields are unchanged. Pass `--description ''` to clear the description. Name, team, and target cannot be changed; to change a target, create a new route.

### Options

<ParamField body="--description" type="TEXT">
  New description (up to 1000 characters). Pass an empty string to clear it.
</ParamField>

<ParamField body="--display-name" type="TEXT">
  New display name (1 to 255 characters). Omit to keep it unchanged.
</ParamField>

<ParamField body="--id" type="TEXT">
  Stable route ID.

  Mutually exclusive with other flags in group `route-ref`.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--name" type="TEXT">
  Exact route name, including its organization-owned prefix.

  Mutually exclusive with other flags in group `route-ref`.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Change a route's description

```sh theme={"system"}
baseten route update --name acme/assistant --description 'Team assistant'
```

### Filter output with `--jq`

Change the display name and print it

```sh theme={"system"}
baseten route update --id <id> --display-name Assistant --jq '.display_name'
```

### Output

**Text mode (`--output text`):** On success, prints "Updated route `name` (`id`)" to stderr; no stdout output.

**JSON mode (`--output json`):** payload type `managementapi.Route`.

target.type is BASETEN\_MODEL\_API, ANTHROPIC, OPENAI, or XAI. Every target includes model. External targets also include secret\_name.

## delete

```sh theme={"system"}
baseten route delete [OPTIONS]
```

Delete a route by ID or exact name. Pass exactly one of `--id` or `--name`.

Prompts for confirmation. Pass `--yes` to skip the prompt. When stdin is not a terminal, `--yes` is required.

### Options

<ParamField body="--id" type="TEXT">
  Stable route ID.

  Mutually exclusive with other flags in group `route-ref`.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--name" type="TEXT">
  Exact route name, including its organization-owned prefix.

  Mutually exclusive with other flags in group `route-ref`.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--yes" type="BOOL">
  Skip the interactive confirmation prompt. Required when stdin is not a terminal.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Delete a route without prompting

```sh theme={"system"}
baseten route delete --name acme/assistant --yes
```

### Filter output with `--jq`

Print the deleted route's ID

```sh theme={"system"}
baseten route delete --id <id> --yes --jq '.id'
```

### Output

**Text mode (`--output text`):** On success, prints "Deleted route `name` (`id`)" to stderr; no stdout output.

**JSON mode (`--output json`):** payload type `managementapi.RouteTombstone`.

## usage

```sh theme={"system"}
baseten route usage [OPTIONS]
```

Show routes usage and estimated costs as daily UTC buckets, oldest first, broken down by the dimensions passed to `--group-by`. Defaults match the API: the previous UTC day through today, grouped by model. Organization admins see usage from every routes API key in the organization; other members see only usage from keys they created.

Usage comes in whole UTC days: `--start` is snapped down to its day and `--end` is rounded up to the end of its day. Every bucket in the window is fetched, paging as needed, until `--limit` buckets are collected. Usage can lag by up to 15 minutes and is retained for 92 days. Model API costs use your prices and include tool calls. OpenAI, Anthropic, and xAI costs estimate what those providers charge and are not Baseten charges. Vertex and OpenAI-compatible usage isn't included.

For your own usage this month, see `baseten harness usage`. For machine-readable streaming, prefer `--output jsonl` over `--output json`.

### Options

<ParamField body="--end" type="TEXT">
  End of the range, exclusive, rounded up to the end of its UTC day. ISO 8601, local when no timezone is given. Defaults to now.
</ParamField>

<ParamField body="--group-by" type="TEXT (repeatable)" default="model">
  Dimension to break usage down by. May be repeated.

  One of: `user`, `model`, `provider`
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--limit" type="INTEGER">
  Maximum number of daily buckets, paging as needed. 0 for no limit.
</ParamField>

<ParamField body="--model" type="TEXT (repeatable)">
  Only return usage for these models. May be repeated.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--provider" type="TEXT (repeatable)">
  Only return usage for these providers. May be repeated.

  One of: `baseten-model-api`, `openai`, `anthropic`, `xai`, `vertex`, `openai-compatible`
</ParamField>

<ParamField body="--since" type="TEXT">
  Window from a relative time ago until now (e.g. '7d'). Mutually exclusive with --start and --end.
</ParamField>

<ParamField body="--start" type="TEXT">
  Start of the range, inclusive, snapped down to its UTC day. ISO 8601, local when no timezone is given. Defaults to the day before --end.
</ParamField>

<ParamField body="--user-id" type="TEXT (repeatable)">
  Only return usage from routes API keys created by these user IDs. May be repeated. 'baseten whoami' shows your own.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Show usage per model since yesterday

```sh theme={"system"}
baseten route usage
```

Show which users drove usage over the last 7 days (admins)

```sh theme={"system"}
baseten route usage --since 7d --group-by user
```

### Filter output with `--jq`

Stream each day's cost per model as a JSONL stream

```sh theme={"system"}
baseten route usage --output jsonl --jq '.results[] | {model, cost_usd}'
```

### Output

**Text mode (`--output text`):** Table with a DATE column, one column per `--group-by` dimension, then INPUT, CACHED, and OUTPUT token counts and COST, followed by an ALL totals row. A day with no usage renders as a single "(no usage)" row. A cost of "-" means some of that usage couldn't be priced. The window goes to stderr. When no day in the window has any usage, prints "No usage in the selected window." to stderr instead of a table.

**JSON mode (`--output json`):** payload type `managementapi.RoutesUsageBucket`.

One record per UTC day, as returned by the API: its date and the per-dimension usage in results, including days with no usage. cost\_usd values are exact decimal strings.