---
title: "How pirouter works"
description: "How a pirouter request travels: the API key picks the workspace and wallet, the model ID picks the candidate providers, the gateway forwards to one deployment and fails over on errors, and the wallet is charged for actual usage. With the glossary of the docs."
canonical: "https://pirouter.ai/docs/how-it-works"
last-updated: "2026-10-17"
lang: "en"
source: "content/docs/en/(start)/how-it-works.mdx"
---

# How pirouter works

How a pirouter request travels: the API key picks the workspace and wallet, the model ID picks the candidate providers, the gateway forwards to one deployment and fails over on errors, and the wallet is charged for actual usage. With the glossary of the docs.

A request finds its workspace and wallet through the API key, and the providers that serve its model through the model ID. The gateway forwards it to one deployment, fails over to the next provider on errors, and charges the wallet for the actual usage when the request ends.

## Seven objects

| Object     | What it is                                                                                                 | Example                                         |
| ---------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| Workspace  | The unit of an account. API keys, the wallet, routing settings, usage and logs all belong to one workspace | The personal workspace created when you sign up |
| API key    | The credential for calling the API. It belongs to one workspace and starts with `sk-pi-`                   | `$PIROUTER_API_KEY`                             |
| Wallet     | The workspace's prepaid balance; every request is charged to it                                            | **Credits** in the console                      |
| Vendor     | The company that makes the model; the first half of the model ID                                           | `openai`, `anthropic`, `google`                 |
| Model      | The `vendor/model` you write in the request                                                                | `openai/gpt-6.1-sol`                            |
| Provider   | The service that runs the model and answers the request                                                    | `anthropic`, `azure`                            |
| Deployment | One instance of a model at a provider, with its own per-minute quota                                       | One deployment of a provider in one region      |

A vendor and a provider can share a name without being the same layer: the vendor of `anthropic/claude-…` is Anthropic, and the provider serving it can be `anthropic` or `azure`.

## How a request travels

1. **Authenticate**: the gateway reads the API key in `Authorization: Bearer` and finds the workspace.
2. **Reserve**: it reserves the estimated cost from the wallet and answers `402` when the balance is too low.
3. **Find candidates**: it finds the providers that serve the model ID, then narrows them with the request's `provider` field and the workspace's routing settings.
4. **Pick a deployment**: it picks one candidate by weight and checks that deployment's quota, answering `429` when it is used up.
5. **Forward**: it sends the request to that deployment. On a failure it moves to the next provider (failover); when every provider has failed and the request lists `models`, it moves to the next model (model fallback).
6. **Settle**: when the request ends it charges the actual usage and releases the rest of the reservation.

Each step has its own page: [Authentication & API keys](https://pirouter.ai/docs/authentication.md), [Pricing & billing](https://pirouter.ai/docs/guides/billing.md), [Provider routing](https://pirouter.ai/docs/guides/routing.md), [Rate limits](https://pirouter.ai/docs/api/rate-limits.md) and [Model fallbacks](https://pirouter.ai/docs/guides/fallbacks.md).

## Glossary

The docs use one word for each concept:

| Term                      | Meaning                                                                     | Not used           |
| ------------------------- | --------------------------------------------------------------------------- | ------------------ |
| Vendor                    | The company that makes a model                                              | —                  |
| Provider                  | The service that serves a model                                             | supplier, upstream |
| Deployment                | One instance of a model at a provider                                       | —                  |
| Failover                  | Moving the same model to another provider                                   | —                  |
| Model fallback            | Moving to the next model in `models`                                        | backup model       |
| API key                   | The credential                                                              | secret, token      |
| Zero data retention (ZDR) | The provider keeps no prompts or responses                                  | —                  |
| Trace ID                  | The `X-Pi-Trace-Id` of every response; include it when you report a problem | request ID         |
| Endpoint                  | One API path, such as `/v1/chat/completions`                                | —                  |

## Console labels

Where the docs quote the console, they use its labels in bold:

| Console label                | Term in the docs |
| ---------------------------- | ---------------- |
| **Providers**                | provider         |
| **Create key**, **API keys** | API key          |
| **Credits**                  | wallet           |
| **Trace ID**                 | trace ID         |

## Next steps

- [Quickstart](https://pirouter.ai/docs/quickstart.md): Create a key, top up, and call a model.
- [Provider routing](https://pirouter.ai/docs/guides/routing.md): How a provider is picked, and how to change it.