docs: clarify Flash Endpoint gpu= single-type vs list placement semantics

flash/configuration/gpu-types.mdx

@@ -1,4 +1,4 @@
 ---
 title: "GPU types"
 sidebarTitle: "GPU types"
 description: "Available GPU pools and specific GPU types for Flash endpoints. Review setup, configuration, deployment, and usage guidance for Runpod Flash."
@@ -6,37 +6,37 @@
 
 Flash provides access to a wide range of NVIDIA GPUs through both pool-based and specific GPU selection. This page lists all available GPU types and explains how to use them.
 
 ## GPU selection methods
 
 Flash offers two ways to specify GPU hardware:
 
 1. [GPU pools](/flash/configuration/gpu-types#gpu-pools) (`GpuGroup`): Select from predefined pools of similar GPUs grouped by architecture and VRAM.
 2. [Specific GPU types](/flash/configuration/gpu-types#specific-gpu-types) (`GpuType`): Target exact GPU models when you need precise hardware characteristics.
 
 You can use either method or mix both for [advanced fallback strategies](/flash/configuration/gpu-types#advanced-fallback-strategies).
 
 ## GPU pools
 
 The `GpuGroup` enum provides access to GPU pools. Each pool contains specific GPU models grouped by architecture and VRAM capacity.
 
 ### Available GPU pools
 
 | GpuGroup | GPUs Included | VRAM | Best For |
 |----------|---------------|------|----------|
 | `GpuGroup.ANY` | Any available GPU | Varies | Fast provisioning, prototyping |
 | `GpuGroup.AMPERE_16` | RTX A4000, RTX 4000 Ada, RTX 2000 Ada | 16GB | Small models, basic inference |
 | `GpuGroup.AMPERE_24` | RTX A4500, RTX A5000, RTX 3090 | 20-24GB | General ML, mid-size models |
 | `GpuGroup.ADA_24` | L4, RTX 4090 | 24GB | Cost-effective inference |
 | `GpuGroup.ADA_32_PRO` | RTX 5090 | 32GB | Latest consumer flagship |
 | `GpuGroup.AMPERE_48` | A40, RTX A6000 | 48GB | Large models, fine-tuning |
 | `GpuGroup.ADA_48_PRO` | L40S, L40, RTX 6000 Ada | 48GB | Professional inference |
 | `GpuGroup.AMPERE_80` | A100 80GB PCIe, A100-SXM4-80GB | 80GB | XL models, intensive training |
 | `GpuGroup.ADA_80_PRO` | H100 80GB HBM3 | 80GB | Cutting-edge inference |
 | `GpuGroup.BLACKWELL_96` | RTX PRO 6000 Blackwell (Server, Workstation, Max-Q) | 96GB | Professional Blackwell workloads |
 | `GpuGroup.HOPPER_141` | H200 | 141GB | Largest models, maximum VRAM |
 | `GpuGroup.BLACKWELL_180` | B200 | 180GB | Maximum VRAM, next-gen training |
 
 ### Using GPU pools
 
 ```python
 from runpod_flash import Endpoint, GpuGroup
@@ -60,59 +60,63 @@
     ...
 ```
 
 ## Specific GPU types
 
 The `GpuType` enum provides access to specific GPU models. Use these when you need exact hardware characteristics.
 
+A single `GpuType` requests that exact card — this is the only form guaranteed to pin workers to a specific GPU model. If you pass a list of `GpuType` values, placement is advisory at the pool/VRAM-tier level instead. See [GPU selection behavior](/flash/configuration/gpu-types#gpu-selection-behavior) for details.
+
 ### Available GPU types
 
 | GpuType | GPU Model | VRAM | Architecture |
 |---------|-----------|------|--------------|
 | `GpuType.ANY` | Any available GPU | Varies | Any |
 | `GpuType.NVIDIA_RTX_A4000` | NVIDIA RTX A4000 | 16GB | Ampere |
 | `GpuType.NVIDIA_RTX_A4500` | NVIDIA RTX A4500 | 20GB | Ampere |
 | `GpuType.NVIDIA_RTX_4000_ADA_GENERATION` | NVIDIA RTX 4000 Ada | 16GB | Ada Lovelace |
 | `GpuType.NVIDIA_RTX_2000_ADA_GENERATION` | NVIDIA RTX 2000 Ada | 16GB | Ada Lovelace |
 | `GpuType.NVIDIA_RTX_A5000` | NVIDIA RTX A5000 | 24GB | Ampere |
 | `GpuType.NVIDIA_L4` | NVIDIA L4 | 24GB | Ada Lovelace |
 | `GpuType.NVIDIA_GEFORCE_RTX_3090` | NVIDIA GeForce RTX 3090 | 24GB | Ampere |
 | `GpuType.NVIDIA_GEFORCE_RTX_4090` | NVIDIA GeForce RTX 4090 | 24GB | Ada Lovelace |
 | `GpuType.NVIDIA_GEFORCE_RTX_5090` | NVIDIA GeForce RTX 5090 | 32GB | Blackwell |
 | `GpuType.NVIDIA_A40` | NVIDIA A40 | 48GB | Ampere |
 | `GpuType.NVIDIA_RTX_A6000` | NVIDIA RTX A6000 | 48GB | Ampere |
 | `GpuType.NVIDIA_RTX_6000_ADA_GENERATION` | NVIDIA RTX 6000 Ada | 48GB | Ada Lovelace |
 | `GpuType.NVIDIA_A100_80GB_PCIe` | NVIDIA A100 80GB PCIe | 80GB | Ampere |
 | `GpuType.NVIDIA_A100_SXM4_80GB` | NVIDIA A100-SXM4-80GB | 80GB | Ampere |
 | `GpuType.NVIDIA_H100_80GB_HBM3` | NVIDIA H100 80GB HBM3 | 80GB | Hopper |
 | `GpuType.NVIDIA_RTX_PRO_6000_BLACKWELL_SERVER_EDITION` | NVIDIA RTX PRO 6000 Blackwell Server Edition | 96GB | Blackwell |
 | `GpuType.NVIDIA_RTX_PRO_6000_BLACKWELL_WORKSTATION_EDITION` | NVIDIA RTX PRO 6000 Blackwell Workstation Edition | 96GB | Blackwell |
 | `GpuType.NVIDIA_RTX_PRO_6000_BLACKWELL_MAX_Q_WORKSTATION_EDITION` | NVIDIA RTX PRO 6000 Blackwell Max-Q Workstation Edition | 96GB | Blackwell |
 | `GpuType.NVIDIA_H200` | NVIDIA H200 | 141GB | Hopper |
 | `GpuType.NVIDIA_B200` | NVIDIA B200 | 180GB | Blackwell |
 
 ### Using specific GPU types
 
 ```python
 from runpod_flash import Endpoint, GpuType
 
-# Single specific GPU
+# Single specific GPU (pins the exact card)
 @Endpoint(name="inference", gpu=GpuType.NVIDIA_A100_80GB_PCIe)
 async def infer(data: dict) -> dict:
     ...
 
-# Multiple specific GPUs (fallback strategy)
+# Multiple specific GPUs (requests any card in this set)
 @Endpoint(
     name="flexible",
     gpu=[
-        GpuType.NVIDIA_A100_80GB_PCIe,  # Try A100 PCIe first
-        GpuType.NVIDIA_A100_SXM4_80GB,  # Fall back to A100 SXM4
-        GpuType.NVIDIA_A40              # Final fallback to A40
+        GpuType.NVIDIA_A100_80GB_PCIe,
+        GpuType.NVIDIA_A100_SXM4_80GB,
+        GpuType.NVIDIA_A40
     ]
 )
 async def flexible_infer(data: dict) -> dict:
     ...
 ```
 
+When you pass a list, the Flash SDK converts each `GpuType` to its GPU pool (`GpuGroup`) when it creates the endpoint, excluding any pool members you didn't list. Placement within the selected pools is advisory: workers may be scheduled on a different card with equivalent VRAM rather than one of the exact models you listed, and list order is not preserved. Pass a single `GpuType` when your workload requires an exact GPU model.
+
 ## Advanced fallback strategies
 
 Combine `GpuGroup` and `GpuType` for robust availability:
@@ -123,45 +127,56 @@
 @Endpoint(
     name="hybrid-selection",
     gpu=[
-        GpuType.NVIDIA_A100_80GB_PCIe,  # Specific GPU first
-        GpuGroup.AMPERE_48,             # Pool fallback
-        GpuGroup.ANY                    # Ultimate fallback
+        GpuType.NVIDIA_A100_80GB_PCIe,  # Specific GPU model
+        GpuGroup.AMPERE_48,             # Any card in the 48GB Ampere pool
+        GpuGroup.ANY                    # Any GPU: expands to all pools for maximum availability
     ]
 )
 async def infer(data: dict) -> dict:
     ...
 ```
 
 ## GPU selection behavior
 
 **Single GPU type:**
-Flash waits for this specific GPU to become available. Jobs stay in queue until capacity is available.
+Passing a single `GpuType` requests that exact GPU model. This is the only form guaranteed to pin workers to a specific card. Flash waits for that model to become available, and jobs stay in queue until capacity is free.
 
 ```python
-gpu=GpuGroup.AMPERE_80  # Only A100 80GB
+gpu=GpuType.NVIDIA_GEFORCE_RTX_4090  # Only the RTX 4090
 ```
 
-**Multiple GPU types (fallback):**
-Flash attempts to provision in the order specified.
+**Single GPU pool:**
+Passing a single `GpuGroup` requests any card in that pool.
+
+```python
+gpu=GpuGroup.AMPERE_80  # Any A100 80GB card
+```
+
+**A list of GPU types or pools:**
+A list requests any one of the listed options. It is not an ordered preference: the SDK does not preserve list order, and placement within the selected pools is advisory — workers may be scheduled on a different card with equivalent VRAM rather than one of the exact models you listed. Be aware of this when benchmarking or when your workload depends on a specific GPU model.
 
 ```python
 gpu=[GpuGroup.AMPERE_80, GpuGroup.AMPERE_48, GpuGroup.ADA_24]
-# Tries: A100 → A40/A6000 → RTX 4090
+# Any card from the 80GB, 48GB, or 24GB pools
 ```
 
 **GpuGroup.ANY:**
 Flash selects the first available GPU based on current capacity.
 
 ```python
 gpu=GpuGroup.ANY  # Fastest provisioning, unpredictable GPU type
 ```
 
+<Note>
+There is currently no API field that reports which GPU model a worker was actually placed on. The endpoint configuration reflects what you requested, not where workers ran, so GPU substitution is invisible in the API. To verify placement, query the GPU from inside the worker (for example, with `nvidia-smi`).
+</Note>
+
 <Tip>
-**For production**: Use specific GPU types for predictable cost and performance.
+**For production**: Pass a single `GpuType` when you need a specific card for predictable cost and performance.
 **For development**: Use `GpuGroup.ANY` for fastest iteration.
 </Tip>
 
 ## Multi-GPU workers
 
 Request multiple GPUs per worker using `gpu_count`:
 
@@ -197,4 +212,4 @@
    gpu=GpuGroup.ANY
    ```
 
 3. **Contact support**: For capacity guarantees, contact [Runpod support](https://www.runpod.io/contact).

flash/configuration/parameters.mdx

@@ -1,4 +1,4 @@
 ---
 title: "Endpoint parameters"
 sidebarTitle: "Parameters"
 description: "Complete reference for all Endpoint class parameters. Review setup, configuration, deployment, and usage guidance for Runpod Flash."
@@ -10,34 +10,34 @@
 
 | Parameter | Type | Description | Default |
 |-----------|------|-------------|---------|
 | `name` | `str` | Endpoint name (required unless `id=` is used) | - |
 | `id` | `str` | Connect to existing endpoint by ID | `None` |
 | `gpu` | `GpuGroup`, `GpuType`, or list | GPU type(s) for the endpoint | `GpuGroup.ANY` |
 | `cpu` | `str` or `CpuInstanceType` | CPU instance type (mutually exclusive with `gpu`) | `None` |
 | `workers` | `int` or `(min, max)` | Worker scaling configuration | `(0, 1)` |
 | `idle_timeout` | `int` | Seconds before scaling down idle workers | `60` |
 | `dependencies` | `list[str]` | Python packages to install | `None` |
 | `system_dependencies` | `list[str]` | System packages to install (apt) | `None` |
 | `accelerate_downloads` | `bool` | Enable download acceleration | `True` |
 | `volume` | `NetworkVolume` or list | Network volume(s) for persistent storage | `None` |
 | `datacenter` | `DataCenter`, list, or `None` | Datacenter(s) for deployment | `None` (all DCs) |
 | `env` | `dict[str, str]` | Environment variables | `None` |
 | `gpu_count` | `int` | GPUs per worker | `1` |
 | `execution_timeout_ms` | `int` | Max execution time in milliseconds | `0` (no limit) |
 | `flashboot` | `bool` | Enable Flashboot fast startup | `True` |
 | `image` | `str` | Custom Docker image to deploy | `None` |
 | `scaler_type` | `ServerlessScalerType` | Scaling strategy | auto |
 | `scaler_value` | `int` | Scaling threshold | `4` |
 | `template` | `PodTemplate` | Pod template overrides | `None` |
 | `min_cuda_version` | `str` or `CudaVersion` | Minimum CUDA version for GPU host selection | `"12.8"` (GPU) / `None` (CPU) |
 | `python_version` | `str` | Python version for the worker image | Local Python |
 
 ## Parameter details
 
 ### name
 
 **Type**: `str`
 **Required**: Yes (unless `id=` is specified)
 
 The endpoint name visible in the [Runpod console](https://console.runpod.io/serverless). Use descriptive names to easily identify endpoints.
 
@@ -50,12 +50,12 @@
 Use naming conventions like `image-generation-prod` or `batch-processor-dev` to organize your endpoints.
 </Tip>
 
 ### id
 
 **Type**: `str`
 **Default**: `None`
 
 Connect to an existing deployed endpoint by its ID. When `id` is specified, `name` is not required.
 
 ```python
 # Connect to existing endpoint
@@ -66,12 +66,16 @@
 result = await ep.post("/inference", {"data": "..."})
 ```
 
 ### gpu
 
 **Type**: `GpuGroup`, `GpuType`, or `list[GpuGroup | GpuType]`
 **Default**: `GpuGroup.ANY` (if neither `gpu` nor `cpu` is specified)
 
-Specifies GPU hardware for the endpoint. Accepts a single GPU type/group or a list for fallback strategies.
+Specifies GPU hardware for the endpoint. Accepts a single GPU pool/type or a list of pools and types:
+
+- A single `GpuType` requests that exact GPU model. This is the only form guaranteed to pin workers to a specific card.
+- A single `GpuGroup` requests any card in that pool.
+- A list requests any of the listed options. The SDK converts each `GpuType` in a list to its GPU pool, so list placement is advisory at the pool/VRAM-tier level: workers may run on a different card with equivalent VRAM rather than one of the exact models you listed, and list order is not preserved.
 
 ```python
 from runpod_flash import Endpoint, GpuType, GpuGroup
@@ -84,14 +88,18 @@
 @Endpoint(name="rtx-worker", gpu=GpuType.NVIDIA_GEFORCE_RTX_4090)
 async def process(data): ...
 
-# Multiple types for fallback
+# Multiple types: requests any card in the set
 @Endpoint(name="flexible", gpu=[GpuType.NVIDIA_A100_80GB_PCIe, GpuType.NVIDIA_RTX_A6000, GpuType.NVIDIA_GEFORCE_RTX_4090])
 async def flexible_infer(data): ...
 ```
 
-See [GPU types](/flash/configuration/gpu-types) for all available options.
+<Note>
+There is currently no API field that reports which GPU model a worker was actually placed on — the endpoint configuration reflects what you requested, not where workers ran. To verify placement, query the GPU from inside the worker (for example, with `nvidia-smi`).
+</Note>
+
+See [GPU types](/flash/configuration/gpu-types) for all available options, including [GPU selection behavior](/flash/configuration/gpu-types#gpu-selection-behavior).
 
 ### cpu
 
 **Type**: `str` or `CpuInstanceType`
 **Default**: `None`
@@ -112,12 +120,12 @@
 
 See [CPU types](/flash/configuration/cpu-types) for all available options.
 
 ### workers
 
 **Type**: `int` or `tuple[int, int]`
 **Default**: `(0, 1)`
 
 Controls worker scaling. Accepts either a single integer (max workers with min=0) or a tuple of (min, max).
 
 ```python
 # Just max: scales from 0 to 5
@@ -135,13 +143,13 @@
 - `workers=(1, N)`: Avoid cold starts by keeping at least one worker warm
 - `workers=(N, N)`: Fixed worker count for consistent performance
 
 ### idle_timeout
 
 **Type**: `int`
 **Default**: `60`
 **Valid range**: 1-3600 seconds
 
 Number of seconds workers will stay active (running) after completing a request, waiting for additional requests before scaling down (to minimum workers).
 
 ```python
 # Quick scale-down for cost savings
@@ -156,7 +164,7 @@
 - `60-120 seconds`: Balanced, variable traffic patterns
 - `120-300 seconds`: Latency-optimized, consistent traffic
 
 ### dependencies
 
 **Type**: `list[str]`
 **Default**: `None`
@@ -176,7 +184,7 @@
 Packages must be imported **inside** the function body, not at the top of your file.
 </Warning>
 
 ### system_dependencies
 
 **Type**: `list[str]`
 **Default**: `None`
@@ -193,12 +201,12 @@
 async def process_video(data): ...
 ```
 
 ### accelerate_downloads
 
 **Type**: `bool`
 **Default**: `True`
 
 Enables faster downloads for dependencies, models, and large files. Disable if you encounter compatibility issues.
 
 ```python
 @Endpoint(
@@ -209,12 +217,12 @@
 async def process(data): ...
 ```
 
 ### volume
 
 **Type**: `NetworkVolume` or `list[NetworkVolume]`
 **Default**: `None`
 
 Attaches network volume(s) for persistent storage. Volumes are mounted at `/runpod-volume/`. Flash uses the volume `name` to find an existing volume or create a new one. Each volume is tied to a specific datacenter.
 
 ```python
 from runpod_flash import Endpoint, GpuGroup, DataCenter, NetworkVolume
@@ -234,7 +242,7 @@
     ...
 ```
 
 For multi-datacenter deployments, pass a list of volumes (one per datacenter):
 
 ```python
 from runpod_flash import Endpoint, GpuGroup, DataCenter, NetworkVolume
@@ -265,12 +273,12 @@
 
 See [Storage](/flash/configuration/storage) for setup instructions.
 
 ### datacenter
 
 **Type**: `DataCenter`, `list[DataCenter]`, `str`, `list[str]`, or `None`
 **Default**: `None` (all available datacenters)
 
 Specifies the datacenter(s) for worker deployment. When set to `None`, the endpoint is available in all datacenters.
 
 ```python
 from runpod_flash import Endpoint, GpuGroup, DataCenter
@@ -308,12 +316,12 @@
 
 | Value | Location |
 |-------|----------|
 | `DataCenter.US_CA_2` | US - California |
 | `DataCenter.US_GA_2` | US - Georgia |
 | `DataCenter.US_IL_1` | US - Illinois |
 | `DataCenter.US_KS_2` | US - Kansas |
 | `DataCenter.US_MD_1` | US - Maryland |
 | `DataCenter.US_MO_1` | US - Missouri |
 | `DataCenter.US_MO_2` | US - Missouri |
 | `DataCenter.US_NC_1` | US - North Carolina |
 | `DataCenter.US_NC_2` | US - North Carolina |
@@ -328,7 +336,7 @@
 CPU endpoints are restricted to `CPU_DATACENTERS`, which currently only includes `EU_RO_1`.
 </Note>
 
 ### env
 
 **Type**: `dict[str, str]`
 **Default**: `None`
@@ -374,7 +382,7 @@
 Environment variables are excluded from configuration hashing. Changing environment values won't trigger endpoint recreation, making it easy to rotate API keys.
 </Note>
 
 ### gpu_count
 
 **Type**: `int`
 **Default**: `1`
@@ -391,12 +399,12 @@
 async def train(data): ...
 ```
 
 ### execution_timeout_ms
 
 **Type**: `int`
 **Default**: `0` (no limit)
 
 Maximum execution time for a single job in milliseconds. Jobs exceeding this timeout are terminated.
 
 ```python
 # 5 minute timeout
@@ -420,7 +428,7 @@
 The Flash SDK's `runsync()` method uses your `execution_timeout_ms` value as the client-side HTTP timeout. If set to a positive value, the SDK waits that duration for the job to complete. If unset or set to `0`, the SDK defaults to a 60-second timeout. For long-running inference jobs, set `execution_timeout_ms` to prevent premature timeouts.
 </Note>
 
 ### flashboot
 
 **Type**: `bool`
 **Default**: `True`
@@ -438,7 +446,7 @@
 
 Set to `False` for debugging or compatibility reasons.
 
 ### image
 
 **Type**: `str`
 **Default**: `None`
@@ -461,14 +469,14 @@
 
 See [Custom Docker images](/flash/custom-docker-images) for complete documentation.
 
 ### scaler_type
 
 **Type**: `ServerlessScalerType`
 **Default**: Auto-selected based on endpoint type
 
 Scaling algorithm strategy. Defaults are automatically set:
 - Queue-based: `QUEUE_DELAY` (scales based on queue depth)
 - Load-balanced: `REQUEST_COUNT` (scales based on active requests)
 
 ```python
 from runpod_flash import Endpoint, ServerlessScalerType
@@ -481,7 +489,7 @@
 async def process(data): ...
 ```
 
 ### scaler_value
 
 **Type**: `int`
 **Default**: `4`
@@ -498,7 +506,7 @@
 async def process(data): ...
 ```
 
 ### template
 
 **Type**: `PodTemplate`
 **Default**: `None`
@@ -519,7 +527,7 @@
 async def process(data): ...
 ```
 
 ## PodTemplate
 
 `PodTemplate` provides advanced pod configuration options:
 
@@ -544,12 +552,12 @@
 For simple environment variables, use the `env` parameter on `Endpoint` instead of `PodTemplate.env`.
 </Tip>
 
 ### min_cuda_version
 
 **Type**: `str` or `CudaVersion`
 **Default**: `"12.8"` for GPU endpoints, `None` for CPU endpoints
 
 Specifies the minimum CUDA driver version required on the host machine. GPU endpoints default to `"12.8"` to ensure workers run on hosts with recent CUDA drivers.
 
 ```python
 from runpod_flash import Endpoint, GpuType, CudaVersion
@@ -581,18 +589,18 @@
 Valid CUDA versions: `CudaVersion.V11_1`, `V11_4`, `V11_7`, `V11_8`, `V12_0`, `V12_1`, `V12_2`, `V12_3`, `V12_4`, `V12_6`, `V12_8` (or equivalent strings like `"12.4"`). Invalid values raise a `ValueError`.
 </Note>
 
 ### python_version
 
 **Type**: `str`
 **Default**: Local Python version
 
 Sets the Python version for the worker image. Supported values: `"3.10"`, `"3.11"`, `"3.12"`, and `"3.13"`.
 
 When you don't specify a Python version, Flash matches your local interpreter (the Python version you run Flash from). The resolution order is:
 
 1. `--python-version` CLI flag (highest priority)
 2. `python_version` declared on resource configs
 3. Your local Python version (`sys.version_info`)
 
 ```python
 from runpod_flash import Endpoint, GpuGroup
@@ -624,11 +632,11 @@
 Python 3.10 reaches end-of-life on 2026-10-31. Consider migrating to Python 3.11 or later.
 </Note>
 
 If your local Python version is not supported (for example, 3.9 or 3.14), the build fails with an actionable error message listing the supported versions.
 
 The `--python-version` CLI flag on `flash build` and `flash deploy` overrides both per-resource declarations and local interpreter detection.
 
 ## EndpointJob
 
 When using `Endpoint(id=...)` or `Endpoint(image=...)`, the `.run()` method returns an `EndpointJob` object for async operations:
 
@@ -661,25 +669,25 @@
 ### Changes that recreate workers
 
 These changes restart all workers:
 - GPU configuration (`gpu`, `gpu_count`)
 - CPU instance type (`cpu`)
 - Docker image (`image`)
 - Storage (`volume`)
 - Datacenter (`datacenter`)
 - Flashboot setting (`flashboot`)
 - CUDA version requirement (`min_cuda_version`)
 - Python version (`python_version`)
 
 Workers are temporarily unavailable during recreation (typically 30-90 seconds).
 
 ### Changes that update settings only
 
 These changes apply immediately with no downtime:
 - Worker scaling (`workers`)
 - Timeouts (`idle_timeout`, `execution_timeout_ms`)
 - Scaler settings (`scaler_type`, `scaler_value`)
 - Environment variables (`env`)
 - Endpoint name (`name`)
 
 ```python
 # First deployment

flash/create-endpoints.mdx

@@ -1,4 +1,4 @@
 ---
 title: "Create endpoints"
 sidebarTitle: "Create endpoints"
 description: "Learn how to create and configure hardware and scaling behavior with the Flash Endpoint class. Review configuration and usage details for Runpod Flash."
@@ -22,7 +22,7 @@
     return {"result": "processed"}
 ```
 
 When you call `run_model(data)`, Flash provisions a GPU <WorkerTooltip /> on Runpod (or reuses an existing one), sends your function code and input to the worker, executes it, and returns the result to your local environment.
 
 Each unique endpoint `name` creates one Serverless endpoint on Runpod with its own URL, scaling configuration, and hardware allocation. The endpoint manages workers that scale up and down based on demand.
 
@@ -81,13 +81,13 @@
 ```
 
 Load-balanced endpoints are ideal for:
 - REST APIs with multiple routes
 - Low-latency request/response patterns
 - Services requiring custom HTTP methods
 
 ### Custom Docker images
 
 Deploy pre-built Docker images (like vLLM or your own workers) and interact with them as a client:
 
 ```python
 from runpod_flash import Endpoint, GpuType
@@ -103,7 +103,7 @@
 models = await vllm.get("/v1/models")
 ```
 
 See [Custom Docker images](/flash/custom-docker-images) for complete documentation, including available images and configuration options.
 
 ### Existing endpoints
 
@@ -123,11 +123,11 @@
 result = await ep.post("/v1/completions", {"prompt": "hello"})
 ```
 
 ## GPU vs CPU
 
 Specify `gpu=` for GPU endpoints or `cpu=` for CPU endpoints. They are mutually exclusive.
 
 ### GPU endpoints
 
 ```python
 from runpod_flash import Endpoint, GpuType, GpuGroup
@@ -140,14 +140,16 @@
 @Endpoint(name="rtx-worker", gpu=GpuType.NVIDIA_GEFORCE_RTX_4090)
 async def render(data: dict) -> dict: ...
 
-# Use multiple GPU types for better availability
+# Use multiple GPU types for better availability (requests any card in the set)
 @Endpoint(name="flexible", gpu=[GpuType.NVIDIA_GEFORCE_RTX_4090, GpuType.NVIDIA_RTX_A5000])
 async def process(data: dict) -> dict: ...
 ```
 
+A single `GpuType` requests that exact card; exact-card placement is only guaranteed with a single `GpuType`. A list requests any card in the set and is treated at the pool/VRAM-tier level, so a worker may run on a different card with equivalent VRAM rather than one of the models you listed. See [GPU selection behavior](/flash/configuration/gpu-types#gpu-selection-behavior) for details.
+
 If neither `gpu=` nor `cpu=` is specified, GPU defaults to `GpuGroup.ANY`.
 
 ### CPU endpoints
 
 ```python
 from runpod_flash import Endpoint, CpuInstanceType
@@ -206,7 +208,7 @@
 
 ### Import packages inside the function body
 
 You must import pip/installed packages **inside the decorated function body**, not at the top of your file. This ensures imports happen on the remote worker. This rule applies to installed packages only; local project modules can be imported at the top of the file because Flash ships their source (see [Import local modules](#import-local-modules)).
 
 **Correct:** imports inside the function.
 ```python
@@ -227,7 +229,7 @@
 
 ### System dependencies
 
 Use `system_dependencies` to install system-level packages (via apt):
 
 ```python
 @Endpoint(
@@ -244,21 +246,21 @@
 
 ## Import local modules
 
 Your endpoint can import local (non-pip) Python modules that live alongside it in your project, such as a sibling `utils.py` file or a `helpers/` package. Flash detects these imports, follows them transitively, and ships the module source to the worker for you, so an import like `import utils` or `from helpers import load` works remotely with no extra configuration.
 
 Flash resolves local imports whether they appear at the top of the file or inside the function body, and it supports absolute imports (`import utils`), relative imports (`from . import helpers`), and dynamic imports with a literal name (`importlib.import_module("plugin")`). It also pulls in the `__init__.py` files for any packages you import. Flash can't resolve dynamic imports whose module name is computed at runtime, so it emits a warning, and you're responsible for making those modules available on the worker.
 
 Flash bundles only local project files. Standard library modules are already present in the worker image, and pip packages must still be declared through the `dependencies` parameter. This applies transitively: if a bundled local module imports a pip package at its top level, that package must still be declared in the `dependencies` of any endpoint that uses the module.
 
 On `flash build` and `flash deploy`, local modules are bundled when they pass the ignore filter, and importing a local module that an ignore rule excludes (or one Flash can't resolve) fails the build. See [Local modules and the ignore filter](/flash/cli/build#local-modules-and-the-ignore-filter) for details.
 
 ### Live execution size limit
 
 When you run an endpoint live (calling an `@Endpoint` function directly, or during `flash dev`), Flash ships the resolved module source inline with the request. The combined source is capped at 8 MiB. If your local dependencies exceed this limit, deploy the app with `flash deploy` instead, which bundles local modules into the build artifact rather than the request payload. See [Local module payload too large](/flash/troubleshooting#local-module-payload-too-large) for the corresponding error.
 
 ### Local modules in a parent directory
 
 On the live execution path, Flash treats a module imported by absolute name from a parent directory as external and doesn't ship it, which causes a `ModuleNotFoundError` on the worker. For example, this happens with `import shared` when `shared.py` sits above your endpoint file. To avoid it, place your endpoint at or above its local dependencies, or use `flash deploy`, which resolves imports against the whole project directory.
 
 ## Parallel execution
 
@@ -312,7 +314,7 @@
 
 ## Persistent storage
 
 Attach a network volume for persistent storage across workers. Each volume is tied to a specific datacenter. Flash uses the volume `name` to find an existing volume or create a new one:
 
 ```python
 from runpod_flash import Endpoint, GpuGroup, DataCenter, NetworkVolume
@@ -330,7 +332,7 @@
     ...
 ```
 
 For multi-datacenter deployments, pass a list of volumes (one per datacenter):
 
 ```python
 from runpod_flash import Endpoint, GpuGroup, DataCenter, NetworkVolume
@@ -356,7 +358,7 @@
 
 For a complete list of parameters available for the `Endpoint` class, see [Endpoint parameters](/flash/configuration/parameters).
 
 ## Working with jobs (client mode)
 
 When using `Endpoint(id=...)` or `Endpoint(image=...)`, you get an `EndpointJob` object for async operations:
 

flash/troubleshooting.mdx

@@ -1,4 +1,4 @@
 ---
 title: "Troubleshooting"
 sidebarTitle: "Troubleshooting"
 description: "Monitor, debug, and troubleshoot Flash deployments. Review setup, configuration, deployment, and usage guidance for Runpod Flash."
@@ -10,7 +10,7 @@
 
 ### Viewing logs
 
 When running Flash functions, logs are displayed in your terminal:
 
 ```text
 2025-11-19 12:35:15,109 | INFO  | Created endpoint: rb50waqznmn2kg - flash-quickstart
@@ -35,7 +35,7 @@
 View detailed metrics and logs in the [Runpod console](https://console.runpod.io/serverless):
 
 1. Navigate to the **Serverless** section.
 2. Click on your endpoint to view:
    - Active workers and queue depth.
    - Request history and job status.
    - Worker logs and execution details.
@@ -48,9 +48,9 @@
 
 1. Go to the [Serverless console](https://console.runpod.io/serverless).
 2. Select your endpoint.
 3. Click on a worker to view its logs.
 
 Logs include dependency installation output, function execution output (print statements, errors), and system-level messages.
 
 ### Add logging to functions
 
@@ -84,7 +84,7 @@
 Get a key: https://docs.runpod.io/get-started/api-keys
 ```
 
 **Cause:** Flash requires a valid Runpod API key to provision and manage endpoints.
 
 **Solution:**
 
@@ -92,18 +92,18 @@
 
 2. Authenticate using one of these methods:
 
    **Option 1: Use `flash login` (recommended)**
    ```bash
    flash login
    ```
    Opens your browser for authentication and saves your credentials.
 
    **Option 2: Environment variable**
    ```bash
    export RUNPOD_API_KEY="your_api_key"
    ```
 
    **Option 3: .env file for local CLI use**
    ```bash
    echo "RUNPOD_API_KEY=your_api_key" >> .env
    ```
@@ -112,7 +112,7 @@
    Values in your `.env` file are only available locally for CLI commands. They are not passed to deployed endpoints.
    </Note>
 
    **Option 4: Shell profile for persistent local access**
    ```bash
    echo 'export RUNPOD_API_KEY="your_api_key"' >> ~/.bashrc
    source ~/.bashrc
@@ -126,9 +126,9 @@
 Run 'flash login' to re-authenticate, or delete the file and retry.
 ```
 
 **Cause:** The credentials file at `~/.runpod/config.toml` contains invalid TOML and cannot be read. This can also appear as "No API key found" even after a successful `flash login`.
 
 **Solution:** Delete the credentials file and re-authenticate:
 
 ```bash
 rm ~/.runpod/config.toml
@@ -142,9 +142,9 @@
 Load-balanced endpoints require route decorators
 ```
 
 **Cause:** Load-balanced endpoints require HTTP method decorators for each route.
 
 **Solution:** Ensure all routes use the correct decorator pattern:
 
 ```python
 from runpod_flash import Endpoint
@@ -161,16 +161,16 @@
     return {"status": "healthy"}
 ```
 
 ### Invalid HTTP method
 
 **Error:**
 ```
 method must be one of {'GET', 'POST', 'PUT', 'DELETE', 'PATCH'}
 ```
 
 **Cause:** The HTTP method specified is not supported.
 
 **Solution:** Use one of the supported HTTP methods: `GET`, `POST`, `PUT`, `DELETE`, or `PATCH`.
 
 ### Invalid path format
 
@@ -179,9 +179,9 @@
 path must start with '/'
 ```
 
 **Cause:** HTTP paths must begin with a forward slash.
 
 **Solution:** Ensure paths start with `/`:
 
 ```python
 # Correct
@@ -198,13 +198,13 @@
 Duplicate route 'POST /process' in endpoint 'my-api'
 ```
 
 **Cause:** Two functions define the same HTTP method and path combination.
 
 **Solution:** Ensure each route is unique within an endpoint. Either change the path or method of one function.
 
 ## Build errors
 
 ### Unsupported Python version
 
 **Error:**
 ```
@@ -212,13 +212,13 @@
 Pass --python-version, declare python_version on a resource config, or run flash from a supported interpreter.
 ```
 
 **Cause:** Flash supports Python 3.10, 3.11, 3.12, and 3.13. Your local Python version is outside this range.
 
 **Solution:**
 
 You have three options:
 
 1. **Use the `--python-version` CLI flag** to override local detection:
    ```bash
    flash build --python-version 3.12
    flash deploy --python-version 3.12
@@ -244,7 +244,7 @@
 Python 3.12 is recommended for best performance with no cold-start overhead. Python 3.10, 3.11, and 3.13 incur additional cold-start overhead on GPU workers because an alternative Python interpreter must be installed.
 </Tip>
 
 ### Local module could not be resolved
 
 **Error:**
 ```
@@ -260,7 +260,7 @@
 Shipping them would silently override a deliberate exclusion, and omitting them would break the worker with ModuleNotFoundError. Remove the matching ignore pattern or stop importing these modules from shipped code.
 ```
 
 **Cause:** This `LocalModuleResolutionError` has two variants: an `@Endpoint` file imports a local module that Flash can't resolve, or shipped code imports a local module that an ignore pattern excludes.
 
 **Solution:**
 
@@ -283,11 +283,11 @@
 Tarball exceeds maximum size. File size: 1.6GB, Max: 1.5GB
 ```
 
 **Cause:** The deployment package exceeds the 1.5GB limit.
 
 **Solution:**
 
 1. Check for large files that shouldn't be included (datasets, model weights, logs).
 2. Add large files to `.gitignore` to exclude them from the build.
 3. Use [network volumes](/flash/configuration/storage) to store large models instead of bundling them.
 
@@ -298,25 +298,25 @@
 File is not a valid gzip file. Expected magic bytes (31, 139)
 ```
 
 **Cause:** The build artifact is corrupted or not a valid gzip file.
 
 **Solution:** Delete the `.flash` directory and rebuild:
 
 ```bash
 rm -rf .flash
 flash build
 ```
 
 ### SSL certificate verification failed
 
 **Error:**
 ```
 SSL certificate verification failed. This usually means Python cannot find your system's CA certificates.
 ```
 
 **Cause:** Python cannot locate the system's trusted CA certificates, preventing secure connections during deployment. This commonly occurs on fresh Python installations, especially on macOS.
 
 **Solution:** Try one of these fixes:
 
 1. **Install certifi and set the certificate bundle path:**
    ```bash
@@ -324,7 +324,7 @@
    export REQUESTS_CA_BUNDLE=$(python -c "import certifi; print(certifi.where())")
    ```
 
 2. **macOS only:** Run the certificate installer that comes with Python. Find it in your Python installation folder (typically `/Applications/Python 3.x/`) and run `Install Certificates.command`.
 
 3. **Add to shell profile for persistence:**
    ```bash
@@ -343,7 +343,7 @@
 Failed to provision resources: [error details]
 ```
 
 **Cause:** Flash couldn't create the Serverless endpoint on Runpod.
 
 **Solutions:**
 
@@ -365,7 +365,7 @@
 Endpoint URL not available - endpoint may not be deployed
 ```
 
 **Cause:** The endpoint function was called before the endpoint finished provisioning.
 
 **Solutions:**
 
@@ -382,7 +382,7 @@
 Execution timeout on [endpoint] after [N]s
 ```
 
 **Cause:** The endpoint function took longer than the configured timeout.
 
 **Solutions:**
 
@@ -397,7 +397,7 @@
 
 2. **Optimize function**: Profile your function to identify bottlenecks.
 
 3. **Use queue-based endpoints**: For long-running tasks, use the `@Endpoint` decorator pattern. Queue-based endpoints are designed for longer operations.
 
 ### Connection failed
 
@@ -406,7 +406,7 @@
 Failed to connect to endpoint [name] ([url])
 ```
 
 **Cause:** Network connectivity issue between your local environment and the Runpod endpoint.
 
 **Solutions:**
 
@@ -414,14 +414,14 @@
 2. **Retry**: Transient network issues often resolve on retry. Flash includes automatic retry logic.
 3. **Check endpoint status**: Verify the endpoint is running in the [Serverless console](https://console.runpod.io/serverless).
 
 ### HTTP errors from endpoint
 
 **Error:**
 ```
 HTTP error from endpoint [name]: 500 - Internal Server Error
 ```
 
 **Cause:** The endpoint function raised an exception during execution.
 
 **Solutions:**
 
@@ -447,7 +447,7 @@
 Failed to deserialize result: [error]
 ```
 
 **Cause:** The function's return value cannot be serialized/deserialized.
 
 **Solutions:**
 
@@ -471,11 +471,11 @@
 Payload size X MB exceeds limit of 10.0 MB
 ```
 
 **Cause:** The serialized argument exceeds the 10 MB limit. Flash uses base64 encoding, which expands data by approximately 33%, so roughly 7.5 MB of raw data becomes 10 MB when encoded.
 
 **Solutions:**
 
 1. **Use network volumes for large data**: Save large data to a network volume and pass the file path:
    ```python
    @Endpoint(name="processor", gpu=GpuGroup.ANY, volume="vol_abc123")
    async def process(file_path: str) -> dict:
@@ -484,7 +484,7 @@
        return {"result": process_data(data)}
    ```
 
 2. **Compress data before sending**: For data that must be passed directly, use compression:
    ```python
    import gzip
 
@@ -502,9 +502,9 @@
 Use `flash deploy` for endpoints with large local dependencies.
 ```
 
 **Cause:** On the live execution path (calling an `@Endpoint` function directly or during `flash dev`), Flash ships your local module source inline with the request, and the combined source exceeds the 8 MiB cap.
 
 **Solution:** Deploy the app with `flash deploy`, which bundles local modules into the build artifact instead of the request payload:
 
 ```bash
 flash deploy
@@ -513,7 +513,7 @@
 uv run flash deploy
 ```
 
 See [Live execution size limit](/flash/create-endpoints#live-execution-size-limit) for details on how local module source is shipped.
 
 ### Deserialization timeout
 
@@ -522,9 +522,9 @@
 Deserialization timed out after 30s
 ```
 
 **Cause:** The deserialization process took longer than 30 seconds. This usually indicates malformed or corrupted serialized data that causes the unpickle operation to hang.
 
 **Solution:** Verify your input data is properly serialized. If you're manually constructing payloads, ensure the data was serialized using `cloudpickle` and encoded with base64. The Flash SDK handles this automatically for programmatic calls.
 
 ### Circuit breaker open
 
@@ -533,23 +533,23 @@
 Circuit breaker is open. Retry in [N] seconds
 ```
 
 **Cause:** Too many consecutive failures to the endpoint triggered the circuit breaker protection.
 
 **Solutions:**
 
 1. **Wait and retry**: The circuit breaker will automatically attempt recovery after the timeout (typically 60 seconds).
 
 2. **Check endpoint health**: Multiple failures usually indicate an underlying issue. Check logs and endpoint status.
 
 3. **Fix the root cause**: Address whatever is causing the repeated failures before retrying.
 
 ## GPU availability issues
 
 ### Job stuck in queue
 
 **Symptom:** Job status shows `IN_QUEUE` for extended periods.
 
 **Cause:** The requested GPU types are not available.
 
 **Solutions:**
 
@@ -558,14 +558,16 @@
    @Endpoint(
        name="flexible",
        gpu=[
-           GpuType.NVIDIA_A100_80GB_PCIe,    # First choice
-           GpuType.NVIDIA_RTX_A6000,         # Fallback
-           GpuType.NVIDIA_GEFORCE_RTX_4090   # Second fallback
+           GpuType.NVIDIA_A100_80GB_PCIe,
+           GpuType.NVIDIA_RTX_A6000,
+           GpuType.NVIDIA_GEFORCE_RTX_4090
        ]
    )
    ```
 
+   A list requests any card in the set — the SDK does not preserve list order. See [GPU selection behavior](/flash/configuration/gpu-types#gpu-selection-behavior) for details.
+
 2. **Use GpuGroup.ANY**: For development, accept any available GPU:
    ```python
    gpu=GpuGroup.ANY
    ```
@@ -578,14 +580,14 @@
 
 ### Module not found
 
 **Error (in worker logs):**
 ```
 ModuleNotFoundError: No module named 'transformers'
 ```
 
 **Cause:** A required dependency was not specified in the `@Endpoint` decorator.
 
 **Solution:** Add all required packages to the `dependencies` parameter:
 
 ```python
 @Endpoint(
@@ -600,11 +602,11 @@
 
 ### Version conflicts
 
 **Symptom:** Function fails with import errors or unexpected behavior.
 
 **Cause:** Dependency version conflicts between packages.
 
 **Solution:** Pin specific versions:
 
 ```python
 @Endpoint(