/vantage/instances/search

POST /api/vantage/instances/search

Price: 1 credit

Search a cloud instance-type catalogue by specs, family and region availability

How to use it

Pick instance types out of one catalogue by hardware shape — vCPU and memory bands, GPU count, architecture, family, bare metal, generation — ordered by type name, vCPU, memory or the cheapest on-demand rate. Matching is exact and literal over the whole catalogue rather than a relevance ranking: `query` is a case-insensitive substring of the type name, display name, family or processor, so nothing is dropped for being a weak match and nothing is added for being similar. `offered_in_region` keeps types that carry a price in a region, while `regions` only chooses which regions' prices come back — ask both when you want cheap types in one region. Each result carries the full spec, benchmark and pricing block, so a follow-up call per type is rarely needed.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• catalog string required — Which cloud catalogue to read (one of: "aws_ec2", "aws_rds", "aws_elasticache", "aws_redshift", "aws_opensearch", "azure_vm", "gcp_compute")
• count integer required — Max number of instance types to return (min: 1; max: 300)
• offset integer — How many matching instance types to skip before the first returned one, in sort order (default: 0; min: 0)
• query string — Case-insensitive substring matched against the instance type, its display name and family (default: ""; examples: "m7g", "graviton", "highmem")
• min_vcpu number nullable — Keep types with at least this many vCPUs
• max_vcpu number nullable — Keep types with at most this many vCPUs
• min_memory_gb number nullable — Keep types with at least this much memory, in GB
• max_memory_gb number nullable — Keep types with at most this much memory, in GB
• min_gpu_count integer nullable — Keep types with at least this many GPUs attached
• architecture string — Keep types whose processor architecture matches, case-insensitive (default: ""; examples: "arm64", "x86_64", "64-bit")
• family string — Case-insensitive substring matched against the family or category label (default: ""; examples: "General purpose", "memory", "Dense Compute")
• bare_metal boolean nullable — Keep only bare-metal types, or only virtualised ones
• current_generation boolean nullable — Keep only current-generation types, or only previous-generation ones
• offered_in_region string — Keep only types that carry a price in this region code (default: ""; examples: "us-east-1", "eu-west-1", "us-central1")
• regions array required — Region codes whose prices are returned, in the provider's own spelling (AWS 'us-east-1', GCP 'us-central1', Azure 'east-us'). At least one is required (examples: ["us-east-1"], ["us-east-1","eu-west-1"]; minItems: 1)
• sort string — Field the results are ordered by (default: "instance_type"; one of: "instance_type", "vcpu", "memory", "on_demand_price")
• descending boolean — Reverse the sort order (default: false)

Response

• @type string (default: "VantageInstance")
• instance_type string required
• catalog string required (one of: "aws_ec2", "aws_rds", "aws_elasticache", "aws_redshift", "aws_opensearch", "azure_vm", "gcp_compute")
• provider string required
• service string required
• url string required
• name string nullable
• azure_name string nullable
• family string nullable
• family_code string nullable
• category string nullable
• generation string nullable
• is_current_generation boolean nullable
• date_introduced string nullable
• service_code string nullable
• service_name string nullable
• compute object nullable
  • @type string (default: "VantageInstanceCompute")
  • vcpu number nullable
  • cores integer nullable
  • vcpus_available integer nullable
  • vcpus_per_core integer nullable
  • memory_gb number nullable
  • memory_per_vcpu_gb number nullable
  • memory_speed_mhz integer nullable
  • physical_processor string nullable
  • processor_architecture string nullable
  • processor_features string nullable
  • architectures array (default: [])
  • clock_speed string nullable
  • ecu number nullable
  • ecu_per_vcpu number nullable
  • azure_compute_units integer nullable
  • normalization_size_factor number nullable
  • azure_size_rank integer nullable
  • is_bare_metal boolean nullable
  • is_shared_cpu boolean nullable
  • is_compute_optimized boolean nullable
  • is_memory_optimized boolean nullable
  • vcpu_by_engine object (default: {})
    • * string
• storage object nullable
  • @type string (default: "VantageInstanceStorage")
  • description string nullable
  • local_disk object nullable
    • @type string (default: "VantageInstanceLocalDisk")
    • devices integer nullable
    • size number nullable
    • size_unit string nullable
    • is_ssd boolean nullable
    • is_nvme_ssd boolean nullable
    • trim_support boolean nullable
    • needs_initialization boolean nullable
    • includes_swap_partition boolean nullable
    • max_write_disks integer nullable
    • read_iops integer nullable
    • write_iops integer nullable
  • ebs object nullable
    • @type string (default: "VantageInstanceEbs")
    • optimized boolean nullable
    • presented_as_nvme boolean nullable
    • iops integer nullable
    • baseline_iops integer nullable
    • max_bandwidth_mbps integer nullable
    • baseline_bandwidth_mbps integer nullable
    • throughput_mibps number nullable
    • baseline_throughput_mibps number nullable
    • dedicated_throughput string nullable
    • min_volume string nullable
    • max_gp2_volume string nullable
    • max_gp3_volume string nullable
  • azure_disk object nullable
    • @type string (default: "VantageInstanceAzureDisk")
    • iops integer nullable
    • read_mbps integer nullable
    • write_mbps integer nullable
    • cached_disk_gb integer nullable
    • uncached_disk_gb integer nullable
    • uncached_disk_iops integer nullable
    • premium_io boolean nullable
    • ultra_ssd boolean nullable
  • has_local_ssd boolean nullable
  • local_ssd_size_gb integer nullable
  • ssd_capacity string nullable
  • max_storage string nullable
  • node_capacity string nullable
  • capacity_per_node string nullable
  • multi_node_capacity string nullable
  • io_throughput string nullable
• network object nullable
  • @type string (default: "VantageInstanceNetwork")
  • performance string nullable
  • baseline_bandwidth_gbps number nullable
  • burst_bandwidth_gbps number nullable
  • enhanced_networking boolean nullable
  • accelerated_networking boolean nullable
  • rdma boolean nullable
  • ipv6_support boolean nullable
  • placement_group_support boolean nullable
  • trunking_compatible boolean nullable
  • branch_interfaces integer nullable
  • max_ecs_tasks integer nullable
  • max_kubernetes_pods integer nullable
  • vpc_only boolean nullable
  • vpc object nullable
    • @type string (default: "VantageInstanceVpc")
    • max_network_interfaces integer nullable
    • ips_per_interface integer nullable
• accelerators object nullable
  • @type string (default: "VantageInstanceAccelerators")
  • gpu_count number nullable
  • gpu_model string nullable
  • gpu_memory_gb number nullable
  • gpu_architectures array (default: [])
  • compute_capability number nullable
  • gpu_clocks array (default: [])
    • @type string (default: "VantageInstanceGpuClocks")
    • graphics_clock_mhz integer nullable
    • sm_clock_mhz integer nullable
    • memory_clock_mhz integer nullable
    • video_clock_mhz integer nullable
  • gpu_average_temperature_celsius number nullable
  • gpu_average_power_draw_watts number nullable
  • fpga_count integer nullable
• benchmarks object nullable
  • @type string (default: "VantageInstanceBenchmarks")
  • coremark_iterations_per_second number nullable
  • ffmpeg_fps number nullable
  • ffmpeg_speed number nullable
  • ffmpeg_used_cuda boolean nullable
• numa object nullable
  • @type string (default: "VantageInstanceNuma")
  • uses_numa boolean nullable
  • node_count integer nullable
  • max_distance integer nullable
  • cores_per_node integer nullable
  • threads_per_node integer nullable
  • memory_per_node_mb number nullable
  • l3_cache_per_node_mb number nullable
  • l3_cache_shared boolean nullable
• features object nullable
  • @type string (default: "VantageInstanceFeatures")
  • intel_avx boolean nullable
  • intel_avx2 boolean nullable
  • intel_avx512 boolean nullable
  • intel_turbo boolean nullable
  • nitro_support boolean nullable
  • nitro_enclave_support boolean nullable
  • eks_auto_mode boolean nullable
  • emr_support boolean nullable
  • linux_virtualization_types array (default: [])
  • baseline_cpu_performance number nullable
  • burst_minutes integer nullable
  • hyperv_generations string nullable
  • vm_deployment string nullable
  • confidential_computing boolean nullable
  • trusted_launch boolean nullable
  • hibernation boolean nullable
  • low_priority boolean nullable
  • capacity_reservation_support boolean nullable
  • host_encryption boolean nullable
  • memory_preserving_maintenance boolean nullable
  • cache_engine string nullable
  • engine_support array (default: [])
    • @type string (default: "VantageInstanceEngineSupport")
    • engine string required
    • min_version string nullable
    • max_version string nullable
  • engine_media_type string nullable
  • deployment_model string nullable
  • unbundled_licensing boolean nullable
  • windows_license_multiplier number nullable
  • max_clients integer nullable
  • max_http_payload string nullable
  • memcached_max_cache_memory_mb number nullable
  • memcached_threads integer nullable
  • redis_maxmemory_bytes number nullable
  • redis_replica_output_buffer_hard_limit_bytes number nullable
  • redis_replica_output_buffer_soft_limit_bytes number nullable
  • node_range string nullable
  • multi_node_range string nullable
  • slices_per_node integer nullable
  • reserved_year string nullable
• regions array (default: [])
  • @type string (default: "VantageInstanceRegion")
  • code string required
  • name string nullable
  • availability_zones array (default: [])
• pricing array (default: [])
  • @type string (default: "VantageInstanceRegionPricing")
  • region string required
  • region_name string nullable
  • price_sets array (default: [])
    • @type string (default: "VantageInstancePriceSet")
    • platform string nullable
    • on_demand number nullable
    • prices object (default: {})
      • * number
    • reserved object (default: {})
      • * number
    • variants array (default: [])
    • percentages object (default: {})
      • * number

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — The entity was not found, or a precondition failed Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.