openapi: "3.0.3"
info:
  title: GridStackHub GPU Pricing API
  description: |
    Real-time GPU cloud pricing across 32+ providers. Returns pricing for H100, B200, A100,
    MI300X, H200, L40S, RTX 4090, and many more GPU models. Data is updated daily via
    automated scrapers. All endpoints are public and require no authentication.

    Use this API to:
    - Compare GPU rental prices across all major cloud providers
    - Find the cheapest provider for a specific GPU model
    - Get the Blackwell Price Index (B200/GB200/B300 pricing)
    - Access aggregated market insights and pricing trends
  version: "1.0.0"
  contact:
    email: gridstackhub@polsia.app
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://gridstackhub.ai
    description: Production

paths:
  /api/gpu-pricing:
    get:
      operationId: getGpuPricing
      summary: Get GPU cloud pricing
      description: |
        Returns current GPU cloud pricing across all tracked providers. Filter by GPU model,
        provider, pricing type, or price range. Results are sorted by per-GPU hourly rate
        ascending by default. Use this endpoint to find the cheapest provider for any GPU,
        compare providers side-by-side, or get a full pricing table for a specific GPU model.

        Common GPU models: H100, B200, A100, A100-80GB, H200, MI300X, L40S, L40, A10G,
        RTX 4090, RTX 3090, V100, T4, A10, GB200, B300.

        Common providers: CoreWeave, Lambda Labs, RunPod, Vast.ai, FluidStack, Shadeform,
        TensorDock, Crusoe Energy, Genesis Cloud, DataCrunch, Nebius, Thunder Compute,
        AWS, Google Cloud, Azure, Oracle Cloud, Hetzner, Scaleway, OVHcloud.
      parameters:
        - name: gpu_model
          in: query
          required: false
          description: Filter by GPU model name. Case-insensitive. Examples: "H100", "B200", "A100", "MI300X", "RTX 4090"
          schema:
            type: string
            example: H100
        - name: provider
          in: query
          required: false
          description: Filter by provider name. Partial match, case-insensitive. Example: "lambda" matches "Lambda Labs"
          schema:
            type: string
            example: Lambda
        - name: min_price
          in: query
          required: false
          description: Minimum per-GPU hourly rate in USD
          schema:
            type: number
            format: float
            example: 1.00
        - name: max_price
          in: query
          required: false
          description: Maximum per-GPU hourly rate in USD
          schema:
            type: number
            format: float
            example: 5.00
        - name: sort
          in: query
          required: false
          description: Sort order for results
          schema:
            type: string
            enum: [price_asc, price_desc, provider]
            default: price_asc
        - name: pricing_type
          in: query
          required: false
          description: Filter by pricing type. "on-demand" is pay-as-you-go, "spot" is interruptible/cheaper, "reserved-1yr" is committed 1-year contract
          schema:
            type: string
            enum: [on-demand, spot, reserved-1yr]
      responses:
        "200":
          description: GPU pricing data
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                example: "*"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GpuPricingResponse"
              example:
                success: true
                count: 3
                as_of: "2026-04-30"
                data:
                  - provider: Shadeform
                    gpu_model: H100
                    gpu_vram_gb: 80
                    instance_type: h100-sxm5-8x
                    gpu_count: 8
                    vcpus: 96
                    ram_gb: 1800
                    hourly_rate: 14.32
                    per_gpu_hourly: 1.79
                    pricing_type: on-demand
                    region: us-east-1
                    interconnect: NVLink
                    egress_cost_per_gb: null
                    storage_cost_per_gb_month: null
                    source_url: https://www.shadeform.ai
                    last_updated: "2026-04-30T00:00:00Z"
                  - provider: Lambda Labs
                    gpu_model: H100
                    gpu_vram_gb: 80
                    instance_type: gpu_8x_h100_sxm5
                    gpu_count: 8
                    vcpus: 120
                    ram_gb: 1800
                    hourly_rate: 15.92
                    per_gpu_hourly: 1.99
                    pricing_type: on-demand
                    region: us-west-3
                    interconnect: NVLink
                    egress_cost_per_gb: 0.05
                    storage_cost_per_gb_month: 0.20
                    source_url: https://lambdalabs.com
                    last_updated: "2026-04-30T00:00:00Z"
        "500":
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/pulse-stack:
    get:
      operationId: getPulseStack
      summary: Get Blackwell Price Index
      description: |
        Returns the Blackwell Price Index — a real-time pricing snapshot for NVIDIA Blackwell
        GPU generation (B200, GB200, B300, B100) plus a full GPU pricing index across all
        tracked models. Also includes top price movers (week-over-week changes), energy cost
        context by US region, and a 30-day forecast flash.

        Use this endpoint when users ask specifically about B200, Blackwell GPU pricing,
        the latest GPU market trends, or want a market-wide snapshot rather than pricing
        for a specific GPU.

        Cache: Results are cached for 1 hour.
      responses:
        "200":
          description: Blackwell Price Index and GPU market snapshot
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                example: "*"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PulseStackResponse"
              example:
                blackwell_price_index:
                  b200:
                    cheapest_provider: Lambda Labs
                    cheapest_hourly: 5.29
                    avg_hourly: 6.12
                    provider_count: 5
                  gb200:
                    cheapest_provider: CoreWeave
                    cheapest_hourly: 9.50
                    avg_hourly: 10.20
                    provider_count: 3
                full_gpu_index:
                  - gpu_model: H100
                    cheapest_hourly: 1.79
                    avg_hourly: 2.45
                    provider_count: 18
                    week_over_week_pct: -2.1
                  - gpu_model: B200
                    cheapest_hourly: 5.29
                    avg_hourly: 6.12
                    provider_count: 5
                    week_over_week_pct: 0.0
                top_movers:
                  - gpu_model: H100
                    provider: Vast.ai
                    change_pct: -5.2
                    direction: down
                generated_at: "2026-04-30T04:00:00Z"
                data_freshness: "2026-04-30T00:00:00Z"
                providers_tracked: 32
                total_pricing_records: 396
        "500":
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/dataset/insights:
    get:
      operationId: getDatasetInsights
      summary: Get aggregated market insights
      description: |
        Returns aggregated GPU cloud market insights derived from the full pricing dataset.
        Includes market-wide statistics, provider distribution, GPU model popularity,
        pricing trends, and demand signals. Use this for high-level market analysis
        or when users want a summary of the GPU cloud market rather than specific pricing.
      responses:
        "200":
          description: Aggregated market insights
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                example: "*"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InsightsResponse"
              example:
                success: true
                generated_at: "2026-04-30T04:00:00Z"
                market_summary:
                  total_providers: 32
                  total_gpu_models: 44
                  total_pricing_records: 396
                  avg_h100_price: 2.45
                  cheapest_h100_price: 1.79
                  cheapest_h100_provider: Shadeform
                top_gpus_by_availability:
                  - gpu_model: H100
                    listing_count: 85
                    provider_count: 18
                  - gpu_model: A100-80GB
                    listing_count: 62
                    provider_count: 15
                price_range_distribution:
                  under_1_per_hour_pct: 12
                  1_to_3_per_hour_pct: 45
                  3_to_10_per_hour_pct: 30
                  over_10_per_hour_pct: 13
        "500":
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/gpu-models:
    get:
      operationId: getGpuModels
      summary: List all tracked GPU models
      description: Returns all distinct GPU models currently tracked in the pricing database with their VRAM specs.
      responses:
        "200":
          description: List of GPU models
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  models:
                    type: array
                    items:
                      type: object
                      properties:
                        gpu_model:
                          type: string
                          example: H100
                        gpu_vram_gb:
                          type: integer
                          example: 80

  /api/providers:
    get:
      operationId: getProviders
      summary: List all tracked cloud providers
      description: Returns all distinct cloud providers with listing counts and price ranges.
      responses:
        "200":
          description: List of providers
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  count:
                    type: integer
                  providers:
                    type: array
                    items:
                      type: object
                      properties:
                        provider:
                          type: string
                          example: Lambda Labs
                        provider_url:
                          type: string
                          example: https://lambdalabs.com
                        listing_count:
                          type: integer
                          example: 12
                        min_hourly:
                          type: number
                          example: 0.50
                        max_hourly:
                          type: number
                          example: 8.99

  /api/stats:
    get:
      operationId: getStats
      summary: Get database statistics
      description: Returns public stats about the pricing database — total listings, providers, GPU models, and data freshness.
      responses:
        "200":
          description: Database statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  pricing:
                    type: object
                    properties:
                      total_listings:
                        type: integer
                      total_providers:
                        type: integer
                      total_gpu_models:
                        type: integer
                      data_freshness:
                        type: string
                        format: date-time

components:
  schemas:
    GpuPricingRecord:
      type: object
      description: A single GPU pricing record from a specific provider
      properties:
        provider:
          type: string
          description: Cloud provider name
          example: Lambda Labs
        gpu_model:
          type: string
          description: GPU model name
          example: H100
        gpu_vram_gb:
          type: integer
          description: GPU VRAM in gigabytes
          example: 80
        instance_type:
          type: string
          description: Provider-specific instance type identifier
          example: gpu_8x_h100_sxm5
        gpu_count:
          type: integer
          description: Number of GPUs in this instance
          example: 8
        vcpus:
          type: integer
          description: Number of vCPUs in this instance
          example: 120
        ram_gb:
          type: integer
          description: System RAM in GB
          example: 1800
        hourly_rate:
          type: number
          format: float
          description: Total instance hourly rate in USD (all GPUs combined)
          example: 15.92
        per_gpu_hourly:
          type: number
          format: float
          description: Per-GPU hourly rate in USD. Use this for apples-to-apples comparison across instance sizes.
          example: 1.99
        pricing_type:
          type: string
          enum: [on-demand, spot, reserved-1yr]
          description: "on-demand: pay-as-you-go, no commitment. spot: interruptible, 20-40% cheaper. reserved-1yr: 1-year committed contract, 20-45% cheaper."
          example: on-demand
        region:
          type: string
          description: Data center region
          example: us-west-3
        interconnect:
          type: string
          nullable: true
          description: GPU interconnect type (NVLink, InfiniBand, PCIe, etc.)
          example: NVLink
        egress_cost_per_gb:
          type: number
          format: float
          nullable: true
          description: Data egress cost in USD per GB. null if not disclosed by provider.
          example: 0.05
        storage_cost_per_gb_month:
          type: number
          format: float
          nullable: true
          description: Block storage cost in USD per GB per month. null if not disclosed.
          example: 0.20
        source_url:
          type: string
          description: Provider pricing page URL
          example: https://lambdalabs.com/service/gpu-cloud
        last_updated:
          type: string
          format: date-time
          description: When this pricing record was last verified
          example: "2026-04-30T00:00:00Z"

    GpuPricingResponse:
      type: object
      properties:
        success:
          type: boolean
        count:
          type: integer
          description: Number of pricing records returned
        as_of:
          type: string
          format: date
          description: Date the data was last refreshed
        data:
          type: array
          items:
            $ref: "#/components/schemas/GpuPricingRecord"

    PulseStackResponse:
      type: object
      properties:
        blackwell_price_index:
          type: object
          description: Current pricing for NVIDIA Blackwell generation GPUs (B200, GB200, B300, B100)
        full_gpu_index:
          type: array
          description: All tracked GPU models with cheapest price, average price, provider count, and week-over-week change
        top_movers:
          type: array
          description: GPUs or providers with the largest week-over-week price changes
        energy_context:
          type: object
          description: US electricity cost context by region — useful for understanding regional price differences
        forecast_flash:
          type: object
          description: 30-day directional price forecast for H100 and A100 (teaser — full forecasts on Pro+)
        generated_at:
          type: string
          format: date-time
        data_freshness:
          type: string
          format: date-time
        providers_tracked:
          type: integer
        total_pricing_records:
          type: integer

    InsightsResponse:
      type: object
      properties:
        success:
          type: boolean
        generated_at:
          type: string
          format: date-time
        market_summary:
          type: object
          description: High-level GPU cloud market statistics
        top_gpus_by_availability:
          type: array
          description: GPU models ranked by number of active listings
        price_range_distribution:
          type: object
          description: Distribution of pricing records across price tiers

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Internal server error
