List Clusters

Overview

The List Clusters endpoint allows you to retrieve all GPU clusters associated with your account with comprehensive filtering, pagination, and sorting options. This is essential for managing large fleets of GPU resources across different projects and environments.

Endpoint

GET https://api.tensorone.ai/v1/clusters

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination (default: 1)
`limit`	integer	No	Number of clusters per page (default: 20, max: 100)
`status`	string	No	Filter by cluster status: `running`, `stopped`, `starting`, `stopping`, `error`, `pending`
`gpu_type`	string	No	Filter by GPU type: `A100`, `H100`, `RTX4090`, `V100`, `T4`
`region`	string	No	Filter by region: `us-east-1`, `us-west-2`, `eu-west-1`, `ap-southeast-1`
`project_id`	string	No	Filter by project ID
`template_id`	string	No	Filter by template ID
`sort_by`	string	No	Sort field: `created_at`, `name`, `status`, `gpu_count`, `cost`
`sort_order`	string	No	Sort order: `asc`, `desc` (default: `desc`)
`search`	string	No	Search clusters by name or description
`min_gpu_count`	integer	No	Minimum number of GPUs
`max_gpu_count`	integer	No	Maximum number of GPUs
`created_after`	string	No	Filter clusters created after date (ISO 8601)
`created_before`	string	No	Filter clusters created before date (ISO 8601)

Request Examples

# List all clusters with basic pagination
curl -X GET "https://api.tensorone.ai/v1/clusters?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Filter running A100 clusters in us-east-1
curl -X GET "https://api.tensorone.ai/v1/clusters?status=running&gpu_type=A100&region=us-east-1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Search and sort clusters by cost
curl -X GET "https://api.tensorone.ai/v1/clusters?search=training&sort_by=cost&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Schema

{
  "success": true,
  "data": {
    "clusters": [
      {
        "id": "cluster_abc123",
        "name": "ml-training-cluster",
        "description": "High-performance cluster for LLM training",
        "status": "running",
        "gpu_type": "A100",
        "gpu_count": 8,
        "cpu_cores": 64,
        "memory_gb": 512,
        "storage_gb": 2000,
        "region": "us-west-2",
        "project_id": "proj_456",
        "template_id": "tmpl_789",
        "ssh_enabled": true,
        "port_mappings": [
          {
            "internal_port": 8080,
            "external_port": 32001,
            "protocol": "tcp"
          }
        ],
        "proxy_url": "https://cluster-abc123.tensorone.ai",
        "ssh_connection": {
          "host": "ssh-abc123.tensorone.ai",
          "port": 22,
          "username": "root"
        },
        "metrics": {
          "gpu_utilization": 85.2,
          "memory_utilization": 67.8,
          "cpu_utilization": 45.1
        },
        "cost": {
          "hourly_rate": 12.50,
          "current_session_cost": 45.75,
          "total_cost": 234.80
        },
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T14:45:00Z",
        "expires_at": "2024-01-16T10:30:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_count": 89,
      "per_page": 20,
      "has_next": true,
      "has_previous": false
    },
    "filters_applied": {
      "status": "running",
      "gpu_type": "A100",
      "region": "us-west-2"
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "response_time_ms": 156
  }
}

Response Fields

Cluster Object

Field	Type	Description
`id`	string	Unique cluster identifier
`name`	string	Human-readable cluster name
`description`	string	Optional cluster description
`status`	string	Current cluster status
`gpu_type`	string	GPU model (A100, H100, RTX4090, etc.)
`gpu_count`	integer	Number of GPUs allocated
`cpu_cores`	integer	Number of CPU cores
`memory_gb`	integer	RAM in gigabytes
`storage_gb`	integer	Persistent storage in gigabytes
`region`	string	Deployment region
`project_id`	string	Associated project ID
`template_id`	string	Template used for cluster creation
`ssh_enabled`	boolean	SSH access availability
`port_mappings`	array	External port mappings
`proxy_url`	string	HTTPS proxy URL for web services
`ssh_connection`	object	SSH connection details
`metrics`	object	Real-time performance metrics
`cost`	object	Cost information and billing
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)
`expires_at`	string	Auto-termination time (if set)

Use Cases

Fleet Management

Monitor and manage large numbers of GPU clusters across different projects and environments.

# Get overview of all running clusters
def get_cluster_overview():
    response = requests.get(
        "https://api.tensorone.ai/v1/clusters",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params={
            "status": "running",
            "sort_by": "cost",
            "sort_order": "desc",
            "limit": 100
        }
    )
    
    clusters = response.json()["data"]["clusters"]
    
    # Calculate total costs and utilization
    total_cost = sum(c["cost"]["hourly_rate"] for c in clusters)
    avg_gpu_util = sum(c["metrics"]["gpu_utilization"] for c in clusters) / len(clusters)
    
    return {
        "total_clusters": len(clusters),
        "total_hourly_cost": total_cost,
        "average_gpu_utilization": avg_gpu_util
    }

Development Environment Discovery

Find available development clusters for team members.

// Find available development clusters
async function findAvailableDevClusters(teamProject) {
  const response = await fetch('https://api.tensorone.ai/v1/clusters?' + 
    new URLSearchParams({
      project_id: teamProject,
      status: 'stopped',
      gpu_type: 'RTX4090',
      sort_by: 'created_at'
    }), {
    headers: {
      'Authorization': 'Bearer ' + API_KEY,
      'Content-Type': 'application/json'
    }
  });
  
  const data = await response.json();
  return data.data.clusters.filter(cluster => 
    cluster.name.includes('dev') || cluster.name.includes('sandbox')
  );
}

Cost Optimization

Identify expensive or underutilized clusters for optimization.

# Find clusters for cost optimization
def find_optimization_candidates():
    response = requests.get(
        "https://api.tensorone.ai/v1/clusters",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params={
            "status": "running",
            "sort_by": "cost",
            "sort_order": "desc"
        }
    )
    
    clusters = response.json()["data"]["clusters"]
    
    # Find underutilized expensive clusters
    candidates = []
    for cluster in clusters:
        if (cluster["cost"]["hourly_rate"] > 10.0 and 
            cluster["metrics"]["gpu_utilization"] < 30.0):
            candidates.append({
                "id": cluster["id"],
                "name": cluster["name"],
                "cost": cluster["cost"]["hourly_rate"],
                "utilization": cluster["metrics"]["gpu_utilization"]
            })
    
    return candidates

Error Handling

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid query parameters provided",
    "details": {
      "limit": "Must be between 1 and 100",
      "gpu_type": "Must be one of: A100, H100, RTX4090, V100, T4"
    }
  }
}

Security Considerations

Authentication: Always use secure API keys with appropriate scopes
Data Privacy: Cluster lists may contain sensitive project information
Rate Limiting: Implement proper rate limiting for automated cluster monitoring
Permissions: Ensure users have appropriate permissions to view cluster information

Best Practices

Pagination: Always use pagination for large cluster fleets to avoid timeouts
Filtering: Use specific filters to reduce API response times and data transfer
Caching: Cache cluster lists for dashboard applications with appropriate TTL
Monitoring: Regularly check cluster status and metrics for proactive management
Cost Control: Monitor expensive clusters and set up alerts for cost thresholds

Authorizations

Authorization

string

header

required

API key authentication. Use 'Bearer YOUR_API_KEY' format.

Response

List of clusters

The response is of type object[].

Getting Started

Account Management

GPU Clusters (VPS)

Serverless Endpoints

Managed Training

AI Services

Payment & Billing

Monitoring & Analytics

Overview

Endpoint

Query Parameters

Request Examples

Response Schema

Response Fields

Cluster Object

Use Cases

Fleet Management

Development Environment Discovery

Cost Optimization

Error Handling

Security Considerations

Best Practices

Authorizations

Response

Getting Started

Account Management

GPU Clusters (VPS)

Serverless Endpoints

Managed Training

AI Services

Payment & Billing

Monitoring & Analytics

​Overview

​Endpoint

​Query Parameters

​Request Examples

​Response Schema

​Response Fields

​Cluster Object

​Use Cases

​Fleet Management

​Development Environment Discovery

​Cost Optimization

​Error Handling

​Security Considerations

​Best Practices

Authorizations

Response

Overview

Endpoint

Query Parameters

Request Examples

Response Schema

Response Fields

Cluster Object

Use Cases

Fleet Management

Development Environment Discovery

Cost Optimization

Error Handling

Security Considerations

Best Practices