Serverless

Create a serverless endpoint

Creates a serverless endpoint. Specify gpu for compute (CPU serverless endpoints are read-only). Container settings can be spread from a template response — see CreateEndpointRequest for the full body.

Returns 201 with the created endpoint. The endpoint can accept jobs immediately, but starts with no active workers unless workers.min is greater than 0. Workers are provisioned on demand and autoscaled between workers.min and workers.max according to the scaling policy, so the first request to an idle endpoint may incur cold-start latency while a worker pulls its image and boots.

POST

serverless

curl --request POST \
  --url https://api.runpod.io/v2/serverless \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "image-generator",
  "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1",
  "gpu": {
    "pools": [
      "ADA_24"
    ],
    "count": 1
  },
  "workers": {
    "min": 0,
    "max": 5
  },
  "scaling": {
    "type": "QUEUE_DELAY",
    "value": 4,
    "idleTimeout": 5
  },
  "dataCenterIds": [
    "US-KS-2"
  ],
  "timeout": 300000
}
'

import requests

url = "https://api.runpod.io/v2/serverless"

payload = {
    "name": "image-generator",
    "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1",
    "gpu": {
        "pools": ["ADA_24"],
        "count": 1
    },
    "workers": {
        "min": 0,
        "max": 5
    },
    "scaling": {
        "type": "QUEUE_DELAY",
        "value": 4,
        "idleTimeout": 5
    },
    "dataCenterIds": ["US-KS-2"],
    "timeout": 300000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'image-generator',
    image: 'runpod/pytorch:2.8.0-py3.11-cuda12.8.1',
    gpu: {pools: ['ADA_24'], count: 1},
    workers: {min: 0, max: 5},
    scaling: {type: 'QUEUE_DELAY', value: 4, idleTimeout: 5},
    dataCenterIds: ['US-KS-2'],
    timeout: 300000
  })
};

fetch('https://api.runpod.io/v2/serverless', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.runpod.io/v2/serverless",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'image-generator',
    'image' => 'runpod/pytorch:2.8.0-py3.11-cuda12.8.1',
    'gpu' => [
        'pools' => [
                'ADA_24'
        ],
        'count' => 1
    ],
    'workers' => [
        'min' => 0,
        'max' => 5
    ],
    'scaling' => [
        'type' => 'QUEUE_DELAY',
        'value' => 4,
        'idleTimeout' => 5
    ],
    'dataCenterIds' => [
        'US-KS-2'
    ],
    'timeout' => 300000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runpod.io/v2/serverless"

	payload := strings.NewReader("{\n  \"name\": \"image-generator\",\n  \"image\": \"runpod/pytorch:2.8.0-py3.11-cuda12.8.1\",\n  \"gpu\": {\n    \"pools\": [\n      \"ADA_24\"\n    ],\n    \"count\": 1\n  },\n  \"workers\": {\n    \"min\": 0,\n    \"max\": 5\n  },\n  \"scaling\": {\n    \"type\": \"QUEUE_DELAY\",\n    \"value\": 4,\n    \"idleTimeout\": 5\n  },\n  \"dataCenterIds\": [\n    \"US-KS-2\"\n  ],\n  \"timeout\": 300000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.runpod.io/v2/serverless")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"image-generator\",\n  \"image\": \"runpod/pytorch:2.8.0-py3.11-cuda12.8.1\",\n  \"gpu\": {\n    \"pools\": [\n      \"ADA_24\"\n    ],\n    \"count\": 1\n  },\n  \"workers\": {\n    \"min\": 0,\n    \"max\": 5\n  },\n  \"scaling\": {\n    \"type\": \"QUEUE_DELAY\",\n    \"value\": 4,\n    \"idleTimeout\": 5\n  },\n  \"dataCenterIds\": [\n    \"US-KS-2\"\n  ],\n  \"timeout\": 300000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.runpod.io/v2/serverless")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"image-generator\",\n  \"image\": \"runpod/pytorch:2.8.0-py3.11-cuda12.8.1\",\n  \"gpu\": {\n    \"pools\": [\n      \"ADA_24\"\n    ],\n    \"count\": 1\n  },\n  \"workers\": {\n    \"min\": 0,\n    \"max\": 5\n  },\n  \"scaling\": {\n    \"type\": \"QUEUE_DELAY\",\n    \"value\": 4,\n    \"idleTimeout\": 5\n  },\n  \"dataCenterIds\": [\n    \"US-KS-2\"\n  ],\n  \"timeout\": 300000\n}"

response = http.request(request)
puts response.read_body

{
  "id": "4m7x2k9q",
  "name": "image-generator",
  "type": "QUEUE_BASED",
  "requestUrls": {
    "run": "https://api.runpod.ai/v2/4m7x2k9q/run",
    "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync"
  },
  "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1",
  "args": "",
  "disk": 20,
  "ports": [
    "8000/http"
  ],
  "env": {
    "MODEL_NAME": "sdxl"
  },
  "registry": null,
  "gpu": {
    "pools": [
      "ADA_24"
    ],
    "count": 1
  },
  "workers": {
    "min": 0,
    "max": 5
  },
  "scaling": {
    "type": "QUEUE_DELAY",
    "value": 4,
    "idleTimeout": 5
  },
  "dataCenterIds": [
    "US-KS-2"
  ],
  "networkVolumes": [
    "2q9m7x4c"
  ],
  "timeout": 300000,
  "flashboot": "OFF",
  "createdAt": "2026-06-01T12:00:00Z"
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "request could not be processed"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing bearer token"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "access denied"
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request validation failed."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "rate limit exceeded for the minute window"
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "errors": [
    "<string>"
  ]
}

Authorizations

Authorization

string

header

required

Runpod API key authentication. Generate an API key in the Runpod console and send it in the Authorization header as Bearer <api_key>. Keys are scoped to the permissions granted when created; requests may return 403 when a valid key lacks access to the requested resource or action.

Body

application/json

Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources.

image

string

required

Docker image reference

Example:

"runpod/pytorch:2.8.0-py3.11-cuda12.8.1"

name

string

required

Minimum string length: 1

Example:

"my-inference"

gpu

object

required

Show child attributes

args

string

Arguments passed to the container entrypoint

Example:

""

disk

integer

Container disk in GB (ephemeral, wiped on restart)

Required range: x >= 1

Example:

50

ports

string[]

Exposed ports, formatted as port/protocol

Example:

["8888/http", "22/tcp"]

env

object

Environment variables as key-value pairs

Show child attributes

Example:

{ "JUPYTER_PASSWORD": "hunter2" }

registry

string | null

Container registry credential ID (for private images)

Example:

null

workers

object

Show child attributes

scaling

object

Show child attributes

dataCenterIds

string[]

Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose.

networkVolumes

string[]

timeout

integer

default:300000

flashboot

enum<string>

default:OFF

FlashBoot cold-start acceleration mode.

OFF — disabled
FLASHBOOT — enabled
PRIORITY_FLASHBOOT — enabled with priority capacity

Available options:

OFF,

FLASHBOOT,

PRIORITY_FLASHBOOT

Response

Created

Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources.

string

required

Example:

"ep_abc123"

name

string

required

Example:

"my-inference"

workers

object

required

Show child attributes

scaling

object

required

Show child attributes

dataCenterIds

string[]

required

Example:

["US-TX-3"]

networkVolumes

string[]

required

Example:

["vol_abc"]

timeout

integer

required

Per-request execution timeout in milliseconds

Example:

300000

flashboot

enum<string>

required

FlashBoot cold-start acceleration mode.

OFF — disabled
FLASHBOOT — enabled
PRIORITY_FLASHBOOT — enabled with priority capacity

Available options:

OFF,

FLASHBOOT,

PRIORITY_FLASHBOOT

createdAt

string<date-time>

required

Example:

"2026-03-13T20:00:00Z"

image

string

Docker image reference

Example:

"runpod/pytorch:2.8.0-py3.11-cuda12.8.1"

args

string

Arguments passed to the container entrypoint

Example:

""

disk

integer

Container disk in GB (ephemeral, wiped on restart)

Required range: x >= 1

Example:

50

ports

string[]

Exposed ports, formatted as port/protocol

Example:

["8888/http", "22/tcp"]

env

object

Environment variables as key-value pairs

Show child attributes

Example:

{ "JUPYTER_PASSWORD": "hunter2" }

registry

string | null

Container registry credential ID (for private images)

Example:

null

type

enum<string>

Request-routing semantics for a modern serverless endpoint.

QUEUE_BASED — submit asynchronous or synchronous jobs through the managed queue.
LOAD_BALANCING — send requests directly to worker-defined HTTP paths.

Available options:

QUEUE_BASED,

LOAD_BALANCING

requestUrls

object

Request submission URLs appropriate to the endpoint's top-level type. Queue-based endpoints provide run and runSync; load-balancing endpoints provide base because their paths are worker-defined.

Option 1
Option 2

Show child attributes

gpu

object | null

Show child attributes

cpu

object | null

Read-only. Present for CPU serverless endpoints; CPU create/update is not yet supported.

Show child attributes

Get a serverless endpointReturns a single serverless endpoint by ID.

Create a serverless endpoint

curl --request POST \
  --url https://api.runpod.io/v2/serverless \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "image-generator",
  "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1",
  "gpu": {
    "pools": [
      "ADA_24"
    ],
    "count": 1
  },
  "workers": {
    "min": 0,
    "max": 5
  },
  "scaling": {
    "type": "QUEUE_DELAY",
    "value": 4,
    "idleTimeout": 5
  },
  "dataCenterIds": [
    "US-KS-2"
  ],
  "timeout": 300000
}
'

import requests

url = "https://api.runpod.io/v2/serverless"

payload = {
    "name": "image-generator",
    "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1",
    "gpu": {
        "pools": ["ADA_24"],
        "count": 1
    },
    "workers": {
        "min": 0,
        "max": 5
    },
    "scaling": {
        "type": "QUEUE_DELAY",
        "value": 4,
        "idleTimeout": 5
    },
    "dataCenterIds": ["US-KS-2"],
    "timeout": 300000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'image-generator',
    image: 'runpod/pytorch:2.8.0-py3.11-cuda12.8.1',
    gpu: {pools: ['ADA_24'], count: 1},
    workers: {min: 0, max: 5},
    scaling: {type: 'QUEUE_DELAY', value: 4, idleTimeout: 5},
    dataCenterIds: ['US-KS-2'],
    timeout: 300000
  })
};

fetch('https://api.runpod.io/v2/serverless', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.runpod.io/v2/serverless",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'image-generator',
    'image' => 'runpod/pytorch:2.8.0-py3.11-cuda12.8.1',
    'gpu' => [
        'pools' => [
                'ADA_24'
        ],
        'count' => 1
    ],
    'workers' => [
        'min' => 0,
        'max' => 5
    ],
    'scaling' => [
        'type' => 'QUEUE_DELAY',
        'value' => 4,
        'idleTimeout' => 5
    ],
    'dataCenterIds' => [
        'US-KS-2'
    ],
    'timeout' => 300000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runpod.io/v2/serverless"

	payload := strings.NewReader("{\n  \"name\": \"image-generator\",\n  \"image\": \"runpod/pytorch:2.8.0-py3.11-cuda12.8.1\",\n  \"gpu\": {\n    \"pools\": [\n      \"ADA_24\"\n    ],\n    \"count\": 1\n  },\n  \"workers\": {\n    \"min\": 0,\n    \"max\": 5\n  },\n  \"scaling\": {\n    \"type\": \"QUEUE_DELAY\",\n    \"value\": 4,\n    \"idleTimeout\": 5\n  },\n  \"dataCenterIds\": [\n    \"US-KS-2\"\n  ],\n  \"timeout\": 300000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.runpod.io/v2/serverless")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"image-generator\",\n  \"image\": \"runpod/pytorch:2.8.0-py3.11-cuda12.8.1\",\n  \"gpu\": {\n    \"pools\": [\n      \"ADA_24\"\n    ],\n    \"count\": 1\n  },\n  \"workers\": {\n    \"min\": 0,\n    \"max\": 5\n  },\n  \"scaling\": {\n    \"type\": \"QUEUE_DELAY\",\n    \"value\": 4,\n    \"idleTimeout\": 5\n  },\n  \"dataCenterIds\": [\n    \"US-KS-2\"\n  ],\n  \"timeout\": 300000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.runpod.io/v2/serverless")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"image-generator\",\n  \"image\": \"runpod/pytorch:2.8.0-py3.11-cuda12.8.1\",\n  \"gpu\": {\n    \"pools\": [\n      \"ADA_24\"\n    ],\n    \"count\": 1\n  },\n  \"workers\": {\n    \"min\": 0,\n    \"max\": 5\n  },\n  \"scaling\": {\n    \"type\": \"QUEUE_DELAY\",\n    \"value\": 4,\n    \"idleTimeout\": 5\n  },\n  \"dataCenterIds\": [\n    \"US-KS-2\"\n  ],\n  \"timeout\": 300000\n}"

response = http.request(request)
puts response.read_body

{
  "id": "4m7x2k9q",
  "name": "image-generator",
  "type": "QUEUE_BASED",
  "requestUrls": {
    "run": "https://api.runpod.ai/v2/4m7x2k9q/run",
    "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync"
  },
  "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1",
  "args": "",
  "disk": 20,
  "ports": [
    "8000/http"
  ],
  "env": {
    "MODEL_NAME": "sdxl"
  },
  "registry": null,
  "gpu": {
    "pools": [
      "ADA_24"
    ],
    "count": 1
  },
  "workers": {
    "min": 0,
    "max": 5
  },
  "scaling": {
    "type": "QUEUE_DELAY",
    "value": 4,
    "idleTimeout": 5
  },
  "dataCenterIds": [
    "US-KS-2"
  ],
  "networkVolumes": [
    "2q9m7x4c"
  ],
  "timeout": 300000,
  "flashboot": "OFF",
  "createdAt": "2026-06-01T12:00:00Z"
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "request could not be processed"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing bearer token"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "access denied"
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request validation failed."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "rate limit exceeded for the minute window"
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "errors": [
    "<string>"
  ]
}

API v2

Pods

Serverless

Templates

Network Volumes

Registries

Catalog

Billing

Create a serverless endpoint

Authorizations

Body

Response