0
# RunPod Python SDK
1

2
A comprehensive Python library for interacting with the RunPod cloud computing platform, offering both API wrapper functionality for managing GPU cloud resources (pods) and a serverless worker SDK for deploying custom endpoints. It enables developers to programmatically create, manage, and interact with GPU-accelerated cloud instances, deploy serverless AI/ML models as custom APIs, and handle job processing in distributed cloud environments.
3

4
## Package Information
5

6
- **Package Name**: runpod
7
- **Language**: Python
8
- **Installation**: `pip install runpod`
9
- **Python Version**: >=3.8
10

11
## Core Imports
12

13
```python
14
import runpod
15
```
16

17
Common usage patterns:
18

19
```python
20
# For pod management
21
from runpod import create_pod, get_pods, terminate_pod
22

23
# For endpoint interactions
24
from runpod import Endpoint, AsyncioEndpoint
25
from typing import Iterator
26

27
# For serverless worker development
28
import runpod.serverless as serverless
29

30
# For configuration
31
from runpod import set_credentials, get_credentials
32
```
33

34
## Basic Usage
35

36
### Pod Management
37

38
```python
39
import runpod
40

41
# Set API credentials
42
runpod.set_credentials("your-api-key")
43

44
# Create a GPU pod
45
pod_config = {
46
    "name": "my-gpu-pod",
47
    "image_name": "runpod/pytorch:1.13.1-py3.10-cuda11.8.0-devel-ubuntu22.04",
48
    "gpu_type_id": "NVIDIA GeForce RTX 3070",
49
    "cloud_type": "SECURE",
50
    "container_disk_in_gb": 10,
51
    "volume_in_gb": 20
52
}
53

54
pod = runpod.create_pod(**pod_config)
55
print(f"Created pod: {pod['id']}")
56

57
# List all pods
58
pods = runpod.get_pods()
59
for pod in pods:
60
    print(f"Pod {pod['id']}: {pod['name']} - {pod['desiredStatus']}")
61

62
# Terminate a pod
63
runpod.terminate_pod(pod['id'])
64
```
65

66
### Endpoint Usage
67

68
```python
69
import runpod
70

71
# Create synchronous endpoint client
72
endpoint = runpod.Endpoint("your-endpoint-id")
73

74
# Run a job
75
job = endpoint.run({
76
    "prompt": "A beautiful landscape painting",
77
    "steps": 50
78
})
79

80
# Get results
81
result = job.output(timeout=300)
82
print(result)
83
```
84

85
### Serverless Worker
86

87
```python
88
import runpod
89

90
def my_handler(job):
91
    """Process a job and return results."""
92
    job_input = job["input"]
93
    
94
    # Your processing logic here
95
    result = {"output": f"Processed: {job_input}"}
96
    
97
    return result
98

99
# Start the serverless worker
100
if __name__ == "__main__":
101
    runpod.serverless.start({
102
        "handler": my_handler,
103
        "return_aggregate_stream": True
104
    })
105
```
106

107
## Architecture
108

109
The RunPod SDK is organized into several key modules:
110

111
- **API Layer**: Direct GraphQL-based API wrapper for cloud resource management
112
- **Endpoint Client**: High-level interfaces for interacting with deployed serverless endpoints
113
- **Serverless SDK**: Framework for building and deploying serverless workers
114
- **CLI Tools**: Command-line interface for development and management workflows
115
- **Configuration**: Credential and environment management utilities
116

117
## Capabilities
118

119
### Pod Management
120

121
Comprehensive pod lifecycle management including creation, monitoring, control, and cleanup of GPU and CPU cloud instances. Supports various GPU types, custom container images, persistent storage volumes, and network configuration.
122

123
```python { .api }
124
def create_pod(name: str, image_name: str, gpu_type_id: str, **kwargs) -> dict: ...
125
def get_pod(pod_id: str) -> dict: ...
126
def get_pods() -> list: ...
127
def stop_pod(pod_id: str) -> dict: ...
128
def resume_pod(pod_id: str) -> dict: ...
129
def terminate_pod(pod_id: str) -> dict: ...
130
```
131

132
[Pod Management](./pod-management.md)
133

134
### GPU and Hardware Management
135

136
Discovery and management of available GPU types, pricing, and availability across different cloud regions. Provides detailed hardware specifications and real-time availability data.
137

138
```python { .api }
139
def get_gpu(gpu_id: str) -> dict: ...
140
def get_gpus() -> list: ...
141
```
142

143
[Pod Management](./pod-management.md)
144

145
### Endpoint Management
146

147
Management of serverless endpoints for deploying AI/ML models as scalable APIs. Handles endpoint creation, template management, scaling configuration, and deployment lifecycle.
148

149
```python { .api }
150
def create_endpoint(**kwargs) -> dict: ...
151
def get_endpoints() -> list: ...
152
def update_endpoint_template(endpoint_id: str, template_id: str) -> dict: ...
153
```
154

155
[Endpoint Management](./endpoint-management.md)
156

157
### Endpoint Client Interface
158

159
High-level client interfaces for interacting with deployed serverless endpoints. Supports both synchronous and asynchronous job submission, real-time status monitoring, output streaming, and job cancellation.
160

161
```python { .api }
162
class Endpoint:
163
    def __init__(self, endpoint_id: str): ...
164
    def run(self, request_input: dict) -> 'Job': ...
165
    def run_sync(self, request_input: dict, timeout: int = 86400) -> dict: ...
166
    def health(self, timeout: int = 3) -> dict: ...
167
    def purge_queue(self, timeout: int = 3) -> dict: ...
168

169
class Job:
170
    def status(self) -> dict: ...
171
    def output(self, timeout: int = 0) -> dict: ...
172
    def stream(self) -> Iterator[dict]: ...
173
    def cancel(self, timeout: int = 3) -> dict: ...
174
```
175

176
[Endpoint Management](./endpoint-management.md)
177

178
### Serverless Worker SDK
179

180
Comprehensive framework for building and deploying serverless workers that process jobs from RunPod endpoints. Includes job processing, progress reporting, error handling, and file transfer utilities.
181

182
```python { .api }
183
def start(config: dict) -> None: ...
184
def progress_update(job_id: str, progress: int, **kwargs) -> None: ...
185
```
186

187
[Serverless Worker SDK](./serverless-worker.md)
188

189
### Configuration and Authentication
190

191
Credential management, API authentication, and configuration utilities for managing multiple profiles and environments.
192

193
```python { .api }
194
def set_credentials(api_key: str, profile: str = "default") -> None: ...
195
def get_credentials(profile: str = "default") -> dict: ...
196
def check_credentials(profile: str = "default") -> bool: ...
197
```
198

199
[Configuration](./configuration.md)
200

201
### Template and Registry Management
202

203
Management of pod templates for consistent deployments and container registry authentication for private images.
204

205
```python { .api }
206
def create_template(**kwargs) -> dict: ...
207
def create_container_registry_auth(**kwargs) -> dict: ...
208
def update_container_registry_auth(auth_id: str, **kwargs) -> dict: ...
209
def delete_container_registry_auth(auth_id: str) -> dict: ...
210
```
211

212
[Pod Management](./pod-management.md)
213

214
### User Account Management
215

216
User profile and account settings management including SSH key configuration and account information retrieval.
217

218
```python { .api }
219
def get_user() -> dict: ...
220
def update_user_settings(**kwargs) -> dict: ...
221
```
222

223
[Configuration](./configuration.md)
224

225
## Global Variables
226

227
```python { .api }
228
__version__: str  # Package version
229
SSH_KEY_PATH: str  # Path to SSH key directory (~/.runpod/ssh)
230
profile: str  # Current configuration profile name
231
api_key: str  # API key for authentication (None if not set)
232
endpoint_url_base: str  # Base URL for API endpoints
233
```