Priority PayGo

Priority pay-as-you-go (Priority PayGo) is a consumption option that provides more consistent performance than Standard PayGo without the upfront commitment of Provisioned Throughput.

When using Priority PayGo, you're charged per token usage at a higher rate than Standard PayGo. For information about pricing, see the Gemini Enterprise Agent Platform pricing page.

When to use Priority PayGo

Priority PayGo is ideal for business critical workloads with fluctuating or unpredictable traffic patterns. The following are example use cases:

  • Customer-facing virtual assistants
  • Agentic workflows and cross-agent interactions
  • Research simulations

Supported models and locations

The following models support Priority PayGo in the global endpoint only. Priority PayGo doesn't support regional or multi-regional endpoints.

Use Priority PayGo

To send requests to the Gemini API using Priority PayGo, you must include the X-Vertex-AI-LLM-Shared-Request-Type header in your request. You can use Priority PayGo in two ways:

  • Use Provisioned Throughput quota (if available) and spill over to Priority PayGo.

  • Use only Priority PayGo.

Use Priority PayGo while using Provisioned Throughput as default

To utilize any available Provisioned Throughput quota before using Priority PayGo, include the header X-Vertex-AI-LLM-Shared-Request-Type: priority in your requests, as shown in the following samples.

Python

Install

pip install --upgrade google-genai

To learn more, see the SDK reference documentation.

Set environment variables to use the Google Gen AI SDK with Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

Initialize your GenAI client to use Priority PayGo. After performing this step, you won't need to make further adjustments to your code to interact with the Gemini API using Priority PayGo on the same client.

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Shared-Request-Type": "priority"
      },
  )
)

REST

After you set up your environment, you can use REST to test a text prompt. The following sample sends a request to the publisher model endpoint.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your project ID. .
  • MODEL_ID: The model ID of the model for which you want to initialize Priority PayGo. For a list of models that support Priority PayGo, see Model versions.
  • PROMPT_TEXT: The text instructions to include in the prompt. JSON.
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

You should receive a JSON response similar to the following.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • Use the generateContent method to request that the response is returned after it's fully generated. To reduce the perception of latency to a human audience, stream the response as it's being generated by using the streamGenerateContent method.
  • The multimodal model ID is located at the end of the URL before the method (for example, gemini-3.5-flash). This sample might support other models as well.

Use only Priority PayGo

To use only Priority PayGo, include the headers X-Vertex-AI-LLM-Request-Type: shared and X-Vertex-AI-LLM-Shared-Request-Type: priority in your requests, as shown in the following samples.

Python

Install

pip install --upgrade google-genai

To learn more, see the SDK reference documentation.

Set environment variables to use the Google Gen AI SDK with Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

Initialize your GenAI client to use Priority PayGo. After performing this step, you won't need to make further adjustments to your code to interact with the Gemini API using Priority PayGo on the same client.

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Request-Type": "shared",
        "X-Vertex-AI-LLM-Shared-Request-Type": "priority"
      },
  )
)

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your project ID. .
  • MODEL_ID: The model ID of the model for which you want to initialize Priority PayGo. For a list of models that support Priority PayGo, see Model versions.
  • PROMPT_TEXT: The text instructions to include in the prompt. JSON.
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

You should receive a JSON response similar to the following.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • Use the generateContent method to request that the response is returned after it's fully generated. To reduce the perception of latency to a human audience, stream the response as it's being generated by using the streamGenerateContent method.
  • The multimodal model ID is located at the end of the URL before the method (for example, gemini-3.5-flash). This sample might support other models as well.

Verify Priority PayGo usage

You can verify whether a request utilized Priority PayGo from the traffic type in the response, as shown in the following examples.

Python

You can verify whether Priority PayGo was utilized for a request from the traffic_type field in the response. If your request was processed using Priority PayGo, the traffic_type field is set to ON_DEMAND_PRIORITY.

sdk_http_response=HttpResponse(
  headers=<dict len=9>
) candidates=[Candidate(
  avg_logprobs=-0.539712212302468,
  content=Content(
    parts=[
      Part(
        text="""Response to sample request.
        """
      ),
    ],
    role='model'
  ),
  finish_reason=<FinishReason.STOP: 'STOP'>
)] create_time=datetime.datetime(2025, 12, 3, 20, 32, 55, 916498, tzinfo=TzInfo(0)) model_version='gemini-2.5-flash' prompt_feedback=None response_id='response_id' usage_metadata=GenerateContentResponseUsageMetadata(
  candidates_token_count=1408,
  candidates_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=1408
    ),
  ],
  prompt_token_count=5,
  prompt_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=5
    ),
  ],
  thoughts_token_count=1356,
  total_token_count=2769,
  traffic_type=<TrafficType.ON_DEMAND_PRIORITY: 'ON_DEMAND_PRIORITY'>
) automatic_function_calling_history=[] parsed=None

REST

You can verify whether Priority PayGo was utilized for a request from the trafficType field in the response. If your request was processed using Priority PayGo, the trafficType field is set to ON_DEMAND_PRIORITY.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}

Throughput limits

Priority PayGo provides a baseline throughput limit at the organization level for each model:

  • Gemini Pro models: 10,000,000 tokens per minute
  • Gemini Flash and Flash-Lite models: 50,000,000 tokens per minute

These limits are available to your organization immediately. There's no ramp-up period, and no need to build sustained usage before you can reach them. Similar to Standard PayGo, the throughput limit shown for a model family applies independently to each model within that family.

Traffic above your limit isn't automatically downgraded. When capacity is available, Agent Platform continues to serve that traffic at priority, and it's billed at Priority PayGo rates. Requests are downgraded to Standard PayGo only when there isn't spare capacity to serve them at priority, and those requests are billed at Standard PayGo rates.

You can verify whether a request was downgraded from the response. For requests downgraded to Standard PayGo, the traffic type is set to ON_DEMAND. For more information, see Verify Priority PayGo usage.

To reduce the chance of a downgrade, smooth traffic across each minute rather than sending sharp, second-level spikes. If your workload requires a higher limit, contact your sales team. For workloads that need dedicated, assured capacity, see Provisioned Throughput.

What's next