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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Sort providers by price, latency, or throughput

> Use request-level provider sorting to prefer the cheapest, fastest, or highest-throughput route for one model.

Use this recipe when the model stays the same but you want the gateway to rank provider offers differently for one request.

## Goal

* Prefer the cheapest provider for one request.
* Prefer the lowest-latency provider for interactive paths.
* Prefer the highest-throughput provider for bulk generation.

## 1. Add `provider.sort` to the request

For text requests, set the sort you want directly on the `provider` object.

```bash cURL theme={null}
curl https://api.phaseo.app/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-lite",
    "input": "Give me one release-note bullet for the last deploy.",
    "provider": {
      "sort": "price"
    }
  }'
```

```typescript TypeScript SDK theme={null}
import Phaseo from "@phaseo/sdk";

const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });

const response = await client.generateResponse({
  model: "google/gemini-3.1-flash-lite",
  input: "Give me one release-note bullet for the last deploy.",
  provider: {
    sort: "price",
  },
});

console.log(response.output_text);
```

```python Python SDK theme={null}
from phaseo import Phaseo

client = Phaseo(api_key="YOUR_API_KEY")

response = client.generate_response(
    {
        "model": "google/gemini-3.1-flash-lite",
        "input": "Give me one release-note bullet for the last deploy.",
        "provider": {
            "sort": "price",
        },
    }
)

print(response.get("output_text"))
```

```go Go SDK theme={null}
package main

import (
  "context"
  "fmt"

  phaseo "github.com/phaseoteam/Phaseo/packages/sdk/sdk-go/v3"
)

func main() {
  client := phaseo.New("YOUR_API_KEY", "https://api.phaseo.app/v1")

  response, err := client.GenerateResponse(context.Background(), phaseo.ResponsesRequest{
    Model: "google/gemini-3.1-flash-lite",
    Input: "Give me one release-note bullet for the last deploy.",
    Provider: map[string]interface{}{
      "sort": "price",
    },
  })
  if err != nil {
    panic(err)
  }

  fmt.Println(response)
}
```

```csharp C# SDK theme={null}
using PhaseoSdk;
using System.Collections.Generic;

var client = new Phaseo("YOUR_API_KEY");

var response = await client.GenerateResponse(new Dictionary<string, object>
{
    ["model"] = "google/gemini-3.1-flash-lite",
    ["input"] = "Give me one release-note bullet for the last deploy.",
    ["provider"] = new Dictionary<string, object>
    {
        ["sort"] = "price"
    }
});

Console.WriteLine(response);
```

```php PHP SDK theme={null}
<?php
require 'vendor/autoload.php';

use Phaseo\Sdk\Phaseo;

$client = new Phaseo(getenv('PHASEO_API_KEY') ?: 'YOUR_API_KEY');

$response = $client->generateResponse([
    'model' => 'google/gemini-3.1-flash-lite',
    'input' => 'Give me one release-note bullet for the last deploy.',
    'provider' => [
        'sort' => 'price',
    ],
]);

print_r($response);
```

```ruby Ruby SDK theme={null}
require 'phaseo_sdk'

client = PhaseoSdk::Phaseo.new(api_key: ENV.fetch('PHASEO_API_KEY', 'YOUR_API_KEY'))

response = client.generate_response(
  model: 'google/gemini-3.1-flash-lite',
  input: 'Give me one release-note bullet for the last deploy.',
  provider: {
    sort: 'price'
  }
)

puts response
```

Supported routing sorts for this flow:

* `price`
* `latency`
* `throughput`

## 2. Pick the sort that matches the workload

Use:

* `price` when cost matters more than tail latency
* `latency` for chat, copilots, and human-in-the-loop tools
* `throughput` for high-volume generation or backfills

## 3. Understand what the gateway compares

When you send an explicit request-level sort, the gateway ranks candidates deterministically instead of using the normal balanced weighted shuffle.

For text models:

* `price` compares a common price basis across the eligible providers
* if shared text meters exist, the gateway prefers matching `input_text_tokens` and `output_text_tokens`
* `latency` uses the latest provider latency data
* `throughput` uses the latest throughput measurements

## 4. Keep the provider pool realistic

Sorting works best after you narrow the candidate pool when needed.

For example, sort only among one approved set of providers:

```bash cURL theme={null}
curl https://api.phaseo.app/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-lite",
    "input": "Summarize the incident in one sentence.",
    "provider": {
      "only": ["google-vertex", "google-vertex-eu"],
      "sort": "latency"
    }
  }'
```

```typescript TypeScript SDK theme={null}
import Phaseo from "@phaseo/sdk";

const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });

const response = await client.generateResponse({
  model: "google/gemini-3.1-flash-lite",
  input: "Summarize the incident in one sentence.",
  provider: {
    only: ["google-vertex", "google-vertex-eu"],
    sort: "latency",
  },
});

console.log(response.output_text);
```

```python Python SDK theme={null}
from phaseo import Phaseo

client = Phaseo(api_key="YOUR_API_KEY")

response = client.generate_response(
    {
        "model": "google/gemini-3.1-flash-lite",
        "input": "Summarize the incident in one sentence.",
        "provider": {
            "only": ["google-vertex", "google-vertex-eu"],
            "sort": "latency",
        },
    }
)

print(response.get("output_text"))
```

```go Go SDK theme={null}
package main

import (
  "context"
  "fmt"

  phaseo "github.com/phaseoteam/Phaseo/packages/sdk/sdk-go/v3"
)

func main() {
  client := phaseo.New("YOUR_API_KEY", "https://api.phaseo.app/v1")

  response, err := client.GenerateResponse(context.Background(), phaseo.ResponsesRequest{
    Model: "google/gemini-3.1-flash-lite",
    Input: "Summarize the incident in one sentence.",
    Provider: map[string]interface{}{
      "only": []string{"google-vertex", "google-vertex-eu"},
      "sort": "latency",
    },
  })
  if err != nil {
    panic(err)
  }

  fmt.Println(response)
}
```

```csharp C# SDK theme={null}
using PhaseoSdk;
using System.Collections.Generic;

var client = new Phaseo("YOUR_API_KEY");

var response = await client.GenerateResponse(new Dictionary<string, object>
{
    ["model"] = "google/gemini-3.1-flash-lite",
    ["input"] = "Summarize the incident in one sentence.",
    ["provider"] = new Dictionary<string, object>
    {
        ["only"] = new[] { "google-vertex", "google-vertex-eu" },
        ["sort"] = "latency"
    }
});

Console.WriteLine(response);
```

```php PHP SDK theme={null}
<?php
require 'vendor/autoload.php';

use Phaseo\Sdk\Phaseo;

$client = new Phaseo(getenv('PHASEO_API_KEY') ?: 'YOUR_API_KEY');

$response = $client->generateResponse([
    'model' => 'google/gemini-3.1-flash-lite',
    'input' => 'Summarize the incident in one sentence.',
    'provider' => [
        'only' => ['google-vertex', 'google-vertex-eu'],
        'sort' => 'latency',
    ],
]);

print_r($response);
```

```ruby Ruby SDK theme={null}
require 'phaseo_sdk'

client = PhaseoSdk::Phaseo.new(api_key: ENV.fetch('PHASEO_API_KEY', 'YOUR_API_KEY'))

response = client.generate_response(
  model: 'google/gemini-3.1-flash-lite',
  input: 'Summarize the incident in one sentence.',
  provider: {
    only: ['google-vertex', 'google-vertex-eu'],
    sort: 'latency'
  }
)

puts response
```

## 5. Verify the ranked outcome

When debugging, inspect the request in **Gateway -> Usage** and look for:

* providers considered
* ranked providers
* the routing score factors for price, latency, or throughput

That makes it easy to confirm whether the gateway sorted the way you expected.

## Related guides

* [Routing and Fallbacks](https://phaseo.app/docs/v1/guides/routing-and-fallbacks.md)
* [Roll out presets and debug routing](https://phaseo.app/docs/v1/cookbook/preset-rollout-and-routing-debug.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.