{ "openapi": "3.1.0", "info": { "title": "Runpod REST API", "version": "2.0.0", "description": "Runpod public REST API — v2" }, "servers": [ { "url": "https://api.runpod.io", "description": "Runpod API v2 production server" } ], "security": [ { "bearerAuth": [] } ], "x-runpod-scopes": { "pods": { "levels": [ "read", "write" ] }, "serverless": { "levels": [ "read", "write" ] }, "clusters": { "levels": [ "read", "write" ] }, "volumes": { "levels": [ "read", "write" ] }, "templates": { "levels": [ "read", "write" ] }, "secrets": { "levels": [ "read", "write" ] }, "authentication": { "levels": [ "read", "write" ] }, "membership": { "levels": [ "read", "write" ] }, "audit": { "levels": [ "read" ] }, "billing": { "levels": [ "read", "write" ] }, "tags": { "levels": [ "read", "write" ] }, "catalog": { "levels": [ "read" ] }, "account": { "levels": [ "read" ] } }, "tags": [ { "name": "Organization", "description": "Organization identity, membership, and access management." }, { "name": "Account", "description": "The account the API key belongs to, and its settings (SSH public keys, secrets)." }, { "name": "Signup", "description": "Email sign-in and account creation for callers without an API key." }, { "name": "Pods", "description": "GPU and CPU pod lifecycle, configuration, actions, and log streaming." }, { "name": "Serverless", "description": "Serverless endpoint lifecycle, worker visibility, releases, and worker log streaming." }, { "name": "Templates", "description": "Reusable pod and endpoint configuration templates." }, { "name": "Network Volumes", "description": "Persistent network storage volumes for workloads." }, { "name": "Global Volumes", "description": "Cross-data-center storage volumes that mount into workloads without pinning them to a data center." }, { "name": "Registries", "description": "Container registry credentials used to pull private images." }, { "name": "Catalog", "description": "Available GPU, CPU, data center, and public template catalog metadata." }, { "name": "Billing", "description": "Billing history and usage cost records across resource types." }, { "name": "Cost Centers", "description": "Named labels that attribute resource spend for billing breakdowns." }, { "name": "Tags", "description": "Key-value labels for organizing and filtering pods, clusters, serverless endpoints, and network volumes." }, { "name": "Audit Logs", "description": "Record of who did what to which resource on the account." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Runpod API Key", "description": "Runpod API key authentication. Generate an API key in the Runpod console and send it in the `Authorization` header as `Bearer `. 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.\n\nConsole sessions (Clerk JWTs) act for the signed-in user. To act for a team instead, also send `X-Team-Id: `; it applies only when the user owns or belongs to that team, otherwise the request runs against the user's own account. API keys created inside a team already act for that team and do not need the header.\n" } }, "responses": { "UnauthorizedError": { "description": "Authentication failed because the bearer token is missing, malformed, expired, or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingBearerToken": { "summary": "Missing bearer token", "value": { "title": "Unauthorized", "status": 401, "detail": "missing bearer token" } } } } } }, "ForbiddenError": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The bearer token is valid, but it does not grant access to the requested resource or action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficientAccess": { "summary": "Insufficient access", "value": { "title": "Forbidden", "status": 403, "detail": "access denied" } } } } } }, "BadRequestError": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The request could not be processed because it is malformed or conflicts with request rules.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badRequest": { "summary": "Bad request", "value": { "title": "Bad Request", "status": 400, "detail": "request could not be processed" } } } } } }, "TemplateReadme": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The template's README, as Markdown.", "content": { "text/markdown; charset=utf-8": { "schema": { "type": "string" }, "examples": { "readme": { "summary": "Successful response", "value": "# PyTorch 2.8\n\nJupyterLab on port 8888.\n" } } } } }, "NotFoundError": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The requested resource was not found or is not accessible to the caller.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notFound": { "summary": "Resource not found", "value": { "title": "Not Found", "status": 404, "detail": "resource not found" } } } } } }, "UnprocessableEntityError": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The request body or parameters were syntactically valid but failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validationFailed": { "summary": "Validation failed", "value": { "title": "Unprocessable Entity", "status": 422, "detail": "Request validation failed." } } } } } }, "RequestTooLargeError": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The incoming request body exceeds 1048576 bytes (1 MiB). Body size is\nchecked after authentication and rate limiting. GET and DELETE reject\nany nonempty request body with `422` instead.\n\nAn operation can also return this status when the request it expands\ninto is too large, even if the incoming body is within the limit.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "requestTooLarge": { "summary": "Request body exceeds the limit", "value": { "title": "Request Entity Too Large", "status": 413, "detail": "Request body exceeds the 1048576 byte limit." } } } } } }, "ResponseTooLargeError": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The response would exceed the response size cap. Request\nfewer items and retry; on paginated operations, lower `limit`.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "responseTooLarge": { "summary": "Response exceeds the size cap", "value": { "title": "Request Entity Too Large", "status": 413, "detail": "Response too large for one request. Request fewer items and retry." } } } } } }, "MethodNotAllowedError": { "description": "The request method is not supported for the target path.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Allow": { "description": "Comma-separated methods supported by the target path.", "schema": { "type": "string" }, "example": "GET, POST" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "methodNotAllowed": { "summary": "Method not allowed", "value": { "title": "Method Not Allowed", "status": 405, "detail": "The requested method is not allowed for this path." } } } } } }, "TooManyRequestsError": { "description": "The caller exceeded its per-user rate limit. The response identifies the window that was exceeded and how long to wait. The `RateLimit` and `RateLimit-Policy` headers (per the IETF ratelimit-headers draft) also accompany successful responses, so clients can track quota before a 429.\n", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, per the exceeded window.", "schema": { "type": "integer" }, "example": 12 }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rateLimited": { "summary": "Rate limit exceeded", "value": { "title": "Too Many Requests", "status": 429, "detail": "rate limit exceeded for the minute window" } } } } } } }, "headers": { "RateLimit": { "description": "Live quota state for the caller, per the IETF ratelimit-headers draft.", "schema": { "$ref": "#/components/schemas/RateLimitHeader" } }, "RateLimit-Policy": { "description": "The quota policy behind `RateLimit`, per the IETF ratelimit-headers draft.", "schema": { "$ref": "#/components/schemas/RateLimitPolicyHeader" } } }, "parameters": { "BillingStartTime": { "name": "startTime", "in": "query", "required": false, "description": "Start of the billing period (RFC 3339). Defaults to 30 days ago. Snapped down to the start of its bucketSize bucket so the window aligns with the returned records; provide a boundary-aligned value (e.g. midnight for bucketSize=day) to avoid widening.\n", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-01T00:00:00Z" }, "BillingEndTime": { "name": "endTime", "in": "query", "required": false, "description": "End of the billing period (RFC 3339), exclusive. Defaults to now. Snapped up to the end of the bucketSize bucket it lands in (unless already on a boundary) so the window aligns with the returned records.\n", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T00:00:00Z" }, "BillingBucketSize": { "name": "bucketSize", "in": "query", "required": false, "description": "Length of each billing time bucket. Defaults to day.", "schema": { "$ref": "#/components/schemas/BillingBucketSize" } }, "BillingLastN": { "name": "lastN", "in": "query", "required": false, "description": "Return the last N buckets of bucketSize, ending with the current (in-progress) bucket — e.g. lastN=100 with bucketSize=day is \"last 100 days\". The resolved window is aligned to bucket boundaries: startTime is the start of the earliest bucket (e.g. midnight of the earliest day) and endTime is the end of the current bucket. Mutually exclusive with startTime/endTime; provide one or the other, not both.\n", "schema": { "type": "integer", "minimum": 1 }, "example": 30 }, "MetricsStartTime": { "name": "startTime", "in": "query", "required": false, "description": "Start of the window (RFC 3339), inclusive. Defaults to 24 hours before endTime, rounded down to the start of an interval bucket. Must be within the last 90 days.\n", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-11T00:00:00Z" }, "MetricsEndTime": { "name": "endTime", "in": "query", "required": false, "description": "End of the window (RFC 3339), exclusive. Defaults to now; a future value is treated as now.\n", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-12T00:00:00Z" }, "MetricsInterval": { "name": "interval", "in": "query", "required": false, "description": "Bucket size. Defaults to 1h.", "schema": { "$ref": "#/components/schemas/EndpointMetricsInterval" } }, "PaginationCursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque resume cursor — pass the previous response's `pagination.nextCursor` through verbatim; omit for the first page. A cursor is only valid for the operation and parameters that issued it; a malformed or foreign cursor is rejected with 422.\n", "schema": { "type": "string", "minLength": 1 }, "example": "Y3JlYXRlZEF0PTE3NDg3ODA0MDA" }, "PaginationLimit": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–1000. Defaults to 1000 when omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 50 }, "ResourceFilters": { "name": "filters", "in": "query", "required": false, "description": "Only return resources matching these filters, as URL-encoded JSON. The filters apply before the page is cut, so send the same value with each `cursor` to keep walking the filtered list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceFilters" }, "example": { "tags": [ { "key": "env", "values": [ "dev", "prod" ] }, { "key": "team" } ] } } } }, "PaginationLimitBuilds": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100. Defaults to 100 when omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 50 }, "PaginationLimitOrganizationGroups": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100. Defaults to 100 when omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 50 }, "PaginationLimitAuditLogs": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Defaults to 200 when omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "example": 50 }, "AuditLogActorIdsFilter": { "name": "actorIds", "in": "query", "required": false, "description": "Only return entries performed by these users. Comma-separated user IDs. Available to organization accounts only; a personal or team account is answered 400.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "user_id_abc_123", "user_id_def_456" ] }, "AuditLogActionsFilter": { "name": "actions", "in": "query", "required": false, "description": "Only return entries whose `action` is one of these names, matched exactly as recorded. Comma-separated.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "create", "delete" ] }, "AuditLogStartTime": { "name": "startTime", "in": "query", "required": false, "description": "Earliest instant to include, inclusive (RFC 3339). The account's audit log retention window still applies: entries that have aged out are not returned even when this reaches further back.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T00:00:00Z" }, "AuditLogEndTime": { "name": "endTime", "in": "query", "required": false, "description": "Latest instant to include, inclusive (RFC 3339). Must be after `startTime` when both are given; 400 otherwise.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-30T23:59:59Z" }, "AuditLogSearch": { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match against `email`, `resourceType`, `resourceId`, `action` and `value`; `actorId` is not searched. Surrounding whitespace is ignored.", "schema": { "type": "string", "minLength": 1 }, "example": "abc123" }, "OrganizationCapabilityFamilyFilter": { "name": "family", "in": "query", "required": false, "description": "Only return these capability families, matched exactly. Comma-separated; a family matching any listed value is returned. An empty value is ignored.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "POD", "ENDPOINT" ] }, "OrganizationCapabilityVerbFilter": { "name": "verb", "in": "query", "required": false, "description": "Only return these verbs, matched exactly. Comma-separated. Each family lists only the requested verbs it has, and a family with none of them is left out. An empty value is ignored.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "VIEW", "USE" ] }, "CatalogIncludeParam": { "name": "include", "in": "query", "required": false, "description": "Comma-separated optional expansions. Supported value today: AVAILABILITY. This may expand with more include values in the future.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/CatalogInclude" } }, "example": [ "AVAILABILITY" ] }, "GpuProductFilter": { "name": "product", "in": "query", "required": false, "description": "Comma-separated availability product contexts. Supported values: POD, CLUSTER, SERVERLESS. Required with include=AVAILABILITY, and valid only with it (400 either way). There is no default: the same GPU type can be scarce for pods and plentiful for serverless, so the context has to be stated rather than assumed.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "example": [ "POD", "SERVERLESS" ] }, "GpuCountFilter": { "name": "count", "in": "query", "required": false, "description": "GPU count for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Defaults to 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 2 }, "GpuCloudFilter": { "name": "cloud", "in": "query", "required": false, "description": "Cloud type for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Supported values: SECURE, COMMUNITY. Default when omitted: SECURE.", "schema": { "$ref": "#/components/schemas/GpuCloudFilter" } }, "CountryCodesFilter": { "name": "countryCodes", "in": "query", "required": false, "description": "Comma-separated ISO 3166-1 alpha-2 country codes, uppercase, to constrain availability to — e.g. FR or FR,DE. Values within this filter use OR semantics. Valid only with include=AVAILABILITY (400 otherwise); a malformed entry is a 422. Scopes availability, lowest-price calculations and the dataCenters array to those countries, so a listed data center outside them is omitted rather than returned with availability NONE. On the list endpoint a GPU type with no data center in those countries drops out entirely; the single-GPU endpoint still returns the requested type, with availability NONE and dataCenters omitted, so a 404 keeps meaning the GPU type does not exist. Read the NONE on availability rather than the absence of dataCenters, which is also absent when availability was not requested.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "example": [ "FR", "DE" ] }, "CudaVersionsFilter": { "name": "cudaVersions", "in": "query", "required": false, "description": "Comma-separated CUDA versions to scope availability and lowest-price calculations to, matched exactly. Format: major.minor, e.g. 12.8 — a bare major is rejected here because it identifies no version. Valid only with include=AVAILABILITY (400 otherwise) and mutually exclusive with minCudaVersion (400 if both are sent); a malformed entry is a 422. Also narrows the returned cudaVersions array; omit it to enumerate every version offered.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+\\.\\d+$" } }, "example": [ "12.8", "12.6" ] }, "MinCudaVersionFilter": { "name": "minCudaVersion", "in": "query", "required": false, "description": "Lowest acceptable CUDA version to scope availability and lowest-price calculations to, compared numerically. Format: integer major or major.minor, e.g. 12 or 12.1 — unlike the `gpu.minCudaVersion` body field on pod and endpoint create, a bare major is accepted here and means any release of that major, because this filter only widens a read. Valid only with include=AVAILABILITY (400 otherwise) and mutually exclusive with cudaVersions (400 if both are sent); a malformed value is a 422. Use this for an open-ended floor and cudaVersions for an exact set.", "schema": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "example": "12.1" }, "CpuProductFilter": { "name": "product", "in": "query", "required": false, "description": "Comma-separated availability product contexts. Supported values for CPUs: POD, SERVERLESS. Required with include=AVAILABILITY, and valid only with it (400 either way). There is no default: availability differs by product.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CpuProduct" }, "example": [ "POD", "SERVERLESS" ] } }, "CpuVCPUCountFilter": { "name": "vcpuCount", "in": "query", "required": false, "description": "Availability vCPU count. Valid only with include=AVAILABILITY. Must be a power of two.", "schema": { "type": "integer", "minimum": 2 }, "example": 4 }, "LogSourceParam": { "name": "source", "in": "query", "required": false, "description": "Log source to stream. Omit to include both container and system logs.", "schema": { "$ref": "#/components/schemas/LogSource" } }, "LogTail": { "name": "tail", "in": "query", "required": false, "description": "Number of historical lines to backfill before streaming. Defaults to\n100 when omitted; set `0` to stream live with no backfill. Maximum 5000.\nIgnored when `since` or `Last-Event-ID` is provided — the resume cursor\ndrives the backfill instead.\n", "schema": { "type": "integer", "minimum": 0, "maximum": 5000, "default": 100 } }, "LogSince": { "name": "since", "in": "query", "required": false, "description": "RFC3339 timestamp to resume from. Ignored when `Last-Event-ID` is\nprovided. When set, the stream resumes from this point and `tail` is\nignored.\n", "schema": { "type": "string", "format": "date-time" } }, "LogLastEventID": { "name": "Last-Event-ID", "in": "header", "required": false, "description": "SSE reconnect cursor — a timestamp emitted by this endpoint. Takes\nprecedence over `since` and `tail`: when present, the stream resumes\nfrom this point. Sent automatically by EventSource on reconnect.\n", "schema": { "type": "string", "format": "date-time" } } }, "schemas": { "Organization": { "type": "object", "description": "The authenticated caller's current organization. Its role and groups are the caller's membership in this organization.", "required": [ "id", "name", "role", "groups" ], "properties": { "id": { "type": "string", "description": "Organization ID.", "examples": [ "org_id_abc_123" ] }, "name": { "type": "string", "description": "Organization name.", "examples": [ "my-org" ] }, "role": { "$ref": "#/components/schemas/OrganizationRoleRef" }, "groups": { "type": "array", "description": "The caller's groups in this organization. Empty when the caller belongs to no groups.", "items": { "$ref": "#/components/schemas/OrganizationGroupRef" } } } }, "OrganizationInvite": { "type": "object", "description": "A pending invitation to join the caller's organization. An invite stops being listed once it is accepted, revoked or expired.", "required": [ "id", "email", "role", "createdAt", "expiresAt" ], "properties": { "id": { "type": "string", "description": "Invite ID.", "examples": [ "invite_id_abc_123" ] }, "email": { "type": "string", "description": "Email address the invitation was sent to. The invitee accepts by signing in with a verified account on this address.", "examples": [ "new-member@example.com" ] }, "role": { "$ref": "#/components/schemas/OrganizationRoleRef" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the invite was sent.", "examples": [ "2026-10-01T09:00:00Z" ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the invite can no longer be accepted.", "examples": [ "2026-10-15T09:00:00Z" ] } } }, "OrganizationRoleRef": { "type": "object", "description": "An organization role, by ID and display name.", "required": [ "id", "type", "name" ], "properties": { "id": { "type": "string", "description": "Role ID. A built-in role's ID is `builtin:` followed by its key; a custom role carries its own ID.", "examples": [ "builtin:dev" ] }, "type": { "$ref": "#/components/schemas/OrganizationRoleType" }, "name": { "type": "string", "description": "The role's display name: `Admin`, `Developer`, `Billing` or `Contributor` for a built-in role, or a custom role's own name. A custom role that has since been deleted reads as `Contributor` while `id` keeps its own ID.", "examples": [ "Developer" ] } } }, "OrganizationRoleType": { "type": "string", "description": "Who defines the role. `builtin` roles are Runpod's: `builtin:admin`, `builtin:dev`, `builtin:billing` and `builtin:basic`. A `custom` role is one the organization defined, under its own ID.", "x-enum-varnames": [ "OrganizationRoleTypeBuiltin", "OrganizationRoleTypeCustom" ], "enum": [ "builtin", "custom" ] }, "OrganizationRoleInput": { "type": "object", "description": "An organization role to assign, by ID.", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "minLength": 1, "description": "Role ID, as reported on a member or an invite: `builtin:admin`, `builtin:dev`, `builtin:billing`, `builtin:basic`, or a custom role's own ID.", "examples": [ "builtin:dev" ] } } }, "ListOrganizationInvitesResponse": { "type": "object", "required": [ "invites" ], "properties": { "invites": { "type": "array", "description": "Pending invites, newest first.", "items": { "$ref": "#/components/schemas/OrganizationInvite" } } } }, "CreateOrganizationInviteRequest": { "type": "object", "additionalProperties": false, "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254, "description": "Address to invite, stored lowercased. The invitee accepts by signing in with a verified account on this address.", "examples": [ "new-member@example.com" ] }, "role": { "$ref": "#/components/schemas/OrganizationRoleInput" } } }, "OrganizationUser": { "type": "object", "description": "A member of the caller's organization. `id` is the member's user ID.", "required": [ "id", "email", "role", "groups" ], "properties": { "id": { "type": "string", "description": "User ID.", "examples": [ "user_id_abc_123" ] }, "email": { "type": [ "string", "null" ], "description": "The member's email address. Null for an account that has none.", "examples": [ "member@example.com" ] }, "role": { "$ref": "#/components/schemas/OrganizationRoleRef" }, "groups": { "type": "array", "description": "The groups the member belongs to, by name.", "items": { "$ref": "#/components/schemas/OrganizationGroupRef" } } } }, "OrganizationGroupRef": { "type": "object", "description": "An organization group, by ID and name.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Group ID.", "examples": [ "group_id_abc_123" ] }, "name": { "type": "string", "description": "Group name.", "examples": [ "Engineering" ] } } }, "ListOrganizationUsersResponse": { "type": "object", "required": [ "users" ], "properties": { "users": { "type": "array", "description": "Every member of the organization.", "items": { "$ref": "#/components/schemas/OrganizationUser" } } } }, "ListOrganizationGroupsResponse": { "type": "object", "required": [ "groups", "pagination" ], "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationGroup" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "OrganizationGroupMember": { "type": "object", "description": "A member of the group. `id` is the member's user ID.", "required": [ "id", "email" ], "properties": { "id": { "type": "string", "description": "User ID.", "examples": [ "user_id_abc_123" ] }, "email": { "type": [ "string", "null" ], "description": "The member's email address. Null for an account that has none.", "examples": [ "member@example.com" ] } } }, "ListOrganizationGroupMembersResponse": { "type": "object", "required": [ "members", "pagination" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationGroupMember" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "OrganizationRole": { "description": "A role an organization member or invite can hold: one of Runpod's built-in roles, or a custom role the organization defined.", "oneOf": [ { "$ref": "#/components/schemas/BuiltinOrganizationRole" }, { "$ref": "#/components/schemas/CustomOrganizationRole" } ], "discriminator": { "propertyName": "type", "mapping": { "builtin": "#/components/schemas/BuiltinOrganizationRole", "custom": "#/components/schemas/CustomOrganizationRole" } } }, "BuiltinOrganizationRole": { "type": "object", "description": "A role Runpod defines. Built-in roles cannot be changed.", "required": [ "id", "name", "type", "capabilities" ], "properties": { "id": { "type": "string", "description": "Role ID, `builtin:` followed by the role's key.", "examples": [ "builtin:dev" ] }, "name": { "type": "string", "description": "Display name.", "examples": [ "Developer" ] }, "type": { "type": "string", "description": "Always `builtin` for this variant.", "x-enum-varnames": [ "BuiltinOrganizationRoleTypeBuiltin" ], "enum": [ "builtin" ] }, "capabilities": { "$ref": "#/components/schemas/OrganizationRoleCapabilities" } } }, "CustomOrganizationRole": { "type": "object", "description": "A role the caller's organization defined.", "required": [ "id", "name", "type", "capabilities", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Role ID.", "examples": [ "cmcustomrole0001" ] }, "name": { "type": "string", "description": "Display name, unique within the organization.", "examples": [ "Pod viewer" ] }, "type": { "type": "string", "description": "Always `custom` for this variant.", "x-enum-varnames": [ "CustomOrganizationRoleTypeCustom" ], "enum": [ "custom" ] }, "capabilities": { "$ref": "#/components/schemas/OrganizationRoleCapabilities" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the role was created.", "examples": [ "2026-10-01T09:00:00Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the role last changed. Assigning the role to a member or invite can also move it.", "examples": [ "2026-10-02T09:00:00Z" ] } } }, "OrganizationRoleCapabilities": { "type": "array", "description": "What the role grants, as `FAMILY:VERB` capabilities, sorted. A member's effective access can also include account-level access that no role grants.", "items": { "type": "string" }, "examples": [ [ "POD:CREATE", "POD:VIEW" ] ] }, "ListOrganizationRolesResponse": { "type": "object", "required": [ "roles" ], "properties": { "roles": { "type": "array", "description": "Built-in and custom roles, oldest first.", "items": { "$ref": "#/components/schemas/OrganizationRole" } } } }, "CreateOrganizationRoleRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "capabilities" ], "properties": { "name": { "$ref": "#/components/schemas/OrganizationRoleName" }, "capabilities": { "$ref": "#/components/schemas/OrganizationRoleCapabilitiesInput" } } }, "UpdateOrganizationRoleRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "The fields to change; omitted fields are unchanged. `capabilities` replaces the role's whole grant set rather than adding to it.", "properties": { "name": { "$ref": "#/components/schemas/OrganizationRoleName" }, "capabilities": { "$ref": "#/components/schemas/OrganizationRoleCapabilitiesInput" } } }, "OrganizationRoleName": { "type": "string", "minLength": 1, "maxLength": 191, "pattern": "[^\\t-\\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]", "description": "Display name, 1–191 characters with at least one non-whitespace character. Leading and trailing whitespace is trimmed. It must be unique within the organization and cannot be a built-in role's name.", "examples": [ "Pod viewer" ] }, "OrganizationRoleCapabilitiesInput": { "type": "array", "description": "What the role grants, as `FAMILY:VERB` capabilities from `GET /v2/organization/roles/capabilities`. The caller must hold every capability it lists.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Z0-9_]+:[A-Z0-9_]+$" }, "examples": [ [ "POD:VIEW" ] ] }, "OrganizationCapabilityCatalog": { "type": "object", "description": "The capabilities a custom role can grant.", "required": [ "version", "families" ], "properties": { "version": { "type": "integer", "description": "Major version of the capability catalog.", "examples": [ 1 ] }, "families": { "type": "array", "description": "Capability families, in catalog order.", "items": { "$ref": "#/components/schemas/OrganizationCapabilityFamily" } } } }, "OrganizationCapabilityFamily": { "type": "object", "required": [ "family", "verbs" ], "properties": { "family": { "type": "string", "description": "What the capability applies to. A capability is written `FAMILY:VERB`, e.g. `POD:VIEW`.", "examples": [ "POD" ] }, "verbs": { "type": "array", "description": "The verbs a custom role can grant on this family, in catalog order.", "items": { "type": "string" }, "examples": [ [ "CREATE", "USE", "TERMINAL", "UPDATE", "DELETE", "VIEW" ] ] } } }, "UpdateOrganizationUserRequest": { "type": "object", "description": "Changes to a member. Send `role`, `groups`, or both; an omitted field is left as it is.", "additionalProperties": false, "minProperties": 1, "properties": { "role": { "$ref": "#/components/schemas/OrganizationRoleInput" }, "groups": { "type": "array", "description": "The member's groups after the change: the whole set, by ID. An empty list removes the member from every group.", "uniqueItems": true, "items": { "$ref": "#/components/schemas/OrganizationGroupInput" } } } }, "OrganizationGroupInput": { "type": "object", "description": "An organization group, by ID.", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "minLength": 1, "description": "Group ID.", "examples": [ "group_id_abc_123" ] } } }, "OrganizationGroup": { "type": "object", "description": "A group in the authenticated caller's organization.", "required": [ "id", "name", "memberCount", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Group ID." }, "name": { "type": "string", "description": "Group name." }, "memberCount": { "type": "integer", "minimum": 0, "description": "Number of group memberships." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Group update time; membership changes need not update it." } } }, "CreateOrganizationGroupRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 191, "pattern": "[^\\t-\\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]", "description": "Group name with at least one non-whitespace character; surrounding whitespace is trimmed.", "examples": [ "Engineering" ] } } }, "UpdateOrganizationGroupRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 191, "pattern": "[^\\t-\\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]", "description": "Group name with at least one non-whitespace character; surrounding whitespace is trimmed.", "examples": [ "Research" ] } } }, "Pagination": { "type": "object", "required": [ "nextCursor", "hasNextPage" ], "description": "Cursor-pagination metadata, uniform across list endpoints. Every response carries it: follow `nextCursor` while `hasNextPage` is true to walk the full result set.\n", "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Pass as the `cursor` query parameter to fetch the next page. Null on the last page.\n", "examples": [ null ] }, "hasNextPage": { "type": "boolean", "description": "Whether more items exist after this page.", "examples": [ false ] } } }, "Paginated": { "type": "object", "description": "Mixin for cursor-paginated list responses. Compose it with `allOf` next to the resource's bare list schema so that a list shape shared with a non-paginated endpoint (e.g. a cluster's member pods) does not inherit a pagination block it cannot honour.\n", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "BaseContainerConfig": { "type": "object", "description": "Container configuration universal to every containerized resource. ContainerConfig composes it and adds `registry`; resources compose ContainerConfig.\n", "properties": { "args": { "type": "string", "description": "The container's command, as a single raw string. This is the field `entrypoint` and `cmd` encode into, exposed in its stored form.\n\nTwo shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console's \"Container start command\" field writes. A JSON object of the form `{\"entrypoint\":[...],\"cmd\":[...]}` sets either or both explicitly.\n\nResponses always return both representations: `args` exactly as stored, plus the deconstructed `entrypoint` and `cmd`. Supplying `args` together with `entrypoint` or `cmd` is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send `\"\"` to clear, omit to leave unchanged.\n", "examples": [ "--model meta-llama/Llama-3-8B --max-model-len 8192", "{\"entrypoint\":[\"/bin/bash\",\"-c\"],\"cmd\":[\"python -u main.py\"]}", "" ] }, "cmd": { "type": "array", "items": { "type": "string" }, "description": "Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n", "examples": [ [ "--model", "meta-llama/Llama-3-8B", "--max-model-len", "8192" ] ] }, "entrypoint": { "type": "array", "items": { "type": "string" }, "description": "Container ENTRYPOINT in exec form, overriding the image's own. Encoded into `args` field; supplying both is allowed only when they describe the same command. Send `[]` to clear, omit to leave unchanged.\n", "examples": [ [ "/bin/bash", "-c" ] ] }, "disk": { "type": "integer", "minimum": 1, "description": "Container disk in GB (ephemeral, wiped on restart)", "examples": [ 50 ] }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Environment variables as key-value pairs", "examples": [ { "JUPYTER_PASSWORD": "hunter2" } ] }, "image": { "type": "string", "description": "Docker image reference", "examples": [ "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404" ] }, "ports": { "type": "array", "description": "Exposed ports, formatted as port/protocol", "items": { "type": "string" }, "examples": [ [ "8888/http", "22/tcp" ] ] } } }, "ContainerConfig": { "description": "Reusable container configuration shared across templates, pods, serverless endpoints, and clusters. Adding a field here automatically propagates to all of them.\n", "allOf": [ { "$ref": "#/components/schemas/BaseContainerConfig" }, { "type": "object", "properties": { "registry": { "type": [ "string", "null" ], "description": "Container registry credential ID for a private image: one of\nyour credentials from `/v2/registries`. Leave it unset for a\nprivate Amazon ECR image. Runpod pulls those with an ECR\ndelegation (`/v2/registries/delegations`) matched to the\nimage's account, region and repository at pull time, so there\nis no delegation ID to pass here (a delegation ID is not a\ncredential ID). A credential set here is used instead of any\ndelegation.\n", "examples": [ null ] } } } ] }, "BaseMounts": { "type": "object", "description": "Shared base type for all resources that mount storage volumes.\n`persistent` and `network` cannot both be set (rejected with 400).\nEach resource that uses this type sets its own limit on network\nvolumes.\n", "properties": { "persistent": { "$ref": "#/components/schemas/PersistentMount" }, "network": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkMount" } } } }, "ClusterMounts": { "description": "Storage mounts for a cluster create: `persistent` or one `network`\nvolume, not both. Clusters cannot mount global volumes, so `global`\nis rejected with 422. A mount `path` must not be empty (rejected with 422): an\nempty path reads as unset and would mount the volume at the\ntemplate's path, or `/workspace` without a template.\n", "x-go-type": "BaseMounts", "allOf": [ { "$ref": "#/components/schemas/BaseMounts" }, { "type": "object", "properties": { "persistent": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 } } }, "network": { "type": "array", "maxItems": 1, "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 } } } } } } ], "unevaluatedProperties": false }, "Mounts": { "description": "Storage mounts attached to a pod. `persistent` (the volume disk) is\nmutually exclusive with both `network` and `global` (enforced at the\nhandler with 400 if combined). A pod takes up to 4 network volumes\nand 1 global volume. Every network volume must be in the pod's data\ncenter, each volume may be listed once, and mount paths must not\noverlap; a request that breaks one of these is rejected. To change a\npod's mounts after creation, see `UpdatePodMounts`.\n", "allOf": [ { "$ref": "#/components/schemas/BaseMounts" }, { "type": "object", "properties": { "network": { "type": "array", "maxItems": 4, "description": "Up to 4 network volumes, all in the pod's data center.\n", "items": { "$ref": "#/components/schemas/NetworkMount" } }, "global": { "type": "array", "maxItems": 1, "description": "At most one global volume, with no data center constraint.\nCombinable with `network` but not with `persistent` (rejected\nwith 400): a persistent disk is dropped whenever a volume is\nattached. Same PATCH rules as `network`.\n", "items": { "$ref": "#/components/schemas/GlobalMount" } } } } ], "unevaluatedProperties": false }, "TemplateMounts": { "type": "object", "additionalProperties": false, "description": "Storage mounts attached to a template. Templates support only a\nsingle persistent mount today; any `network` property is rejected\nwith 422 by the schema validator.\n\nPATCH semantics: omitting `mounts` or sending `{}` leaves the\nexisting mount unchanged.\n", "properties": { "persistent": { "$ref": "#/components/schemas/PersistentMount" } } }, "PersistentMount": { "type": "object", "required": [ "size", "path" ], "additionalProperties": false, "description": "Host-local persistent storage. Pinned to the pod's host machine — data\ndoes not survive a host failure. Disallowed on CPU pods. Mutually\nexclusive with NetworkMount. Deprecated: prefer NetworkMount for any\ndata you cannot recreate.\n", "properties": { "size": { "type": "integer", "minimum": 10, "description": "Host-local persistent storage in GB. Minimum 10 GB.", "examples": [ 20 ] }, "path": { "type": "string", "description": "Mount path inside the container. May be changed via PATCH.", "examples": [ "/workspace" ] } } }, "NetworkMount": { "type": "object", "required": [ "volumeId", "path" ], "additionalProperties": false, "description": "Reference to a NetworkVolume. Custom paths are honored at runtime on\nboth GPU and CPU pods. On a pod, the volume can be mounted, moved,\nor unmounted after creation (see `UpdatePodMounts`).\n", "properties": { "volumeId": { "type": "string", "description": "ID of an existing NetworkVolume in the same data center as the pod.", "examples": [ "vol_xyz" ] }, "path": { "type": "string", "description": "Mount path inside the container. No default — must be specified explicitly.", "examples": [ "/runpod-volume" ] } } }, "GlobalMount": { "type": "object", "required": [ "volumeId" ], "additionalProperties": false, "description": "Reference to a GlobalVolume. Usage-billed, so it has no size. On a\npod, the volume can be mounted, moved, or unmounted after creation\n(see `UpdatePodMounts`).\n", "properties": { "volumeId": { "type": "string", "description": "ID of an existing GlobalVolume.", "examples": [ "gsb_abc" ] }, "path": { "type": "string", "description": "Mount path inside the container. Optional; a default is chosen for you when omitted.", "examples": [ "/data" ] } } }, "UpdatePodMounts": { "type": "object", "additionalProperties": false, "description": "Changes to a pod's mounts. Each entry names one volume by `volumeId`\nand changes only that volume; volumes that are not listed, and kinds\nthat are omitted, are left as they are. Omitting `mounts` or sending\n`{}` changes nothing.\n\n- A listed volume the pod does not have is mounted at `path`.\n- A listed volume the pod already has moves to `path` (or stays\n put when `path` is omitted).\n- `remove: true` unmounts the volume. It cannot be combined with\n `path`, and the volume must be mounted on the pod.\n- To swap a volume, remove the old one and add the new one in the\n same request.\n\nLimits are checked against the pod as it would be after the request\nand rejected with 400: at most 4 network volumes and 1 global\nvolume, and a volume disk cannot share a pod with network or global\nvolumes. A volume disk can be added to a pod that has no volumes\nmounted (or unmounts them all in the same request), and it can only\ngrow. Removing a volume disk is not supported yet.\n", "properties": { "persistent": { "$ref": "#/components/schemas/PersistentMountPatch" }, "network": { "type": "array", "maxItems": 8, "description": "Network volumes to mount, move, or unmount. Up to 8 entries, so\na request can unmount 4 volumes and mount 4 others; the pod can\nstill hold at most 4 afterwards.\n", "items": { "$ref": "#/components/schemas/NetworkMountPatch" } }, "global": { "type": "array", "maxItems": 2, "description": "Global volumes to mount, move, or unmount. Up to 2 entries, so a\nrequest can swap the global volume; the pod can still hold at\nmost 1 afterwards.\n", "items": { "$ref": "#/components/schemas/GlobalMountPatch" } } } }, "PersistentMountPatch": { "type": "object", "additionalProperties": false, "description": "Adds the pod's volume disk, grows it, or moves it. Adding a disk\nrequires `size`; on a pod that already has one, omitted fields are\nleft as they are. Not available on CPU pods.\n", "properties": { "size": { "type": "integer", "minimum": 10, "description": "Volume disk size in GB. Can only grow; a smaller size than the current one is rejected with 400.", "examples": [ 50 ] }, "path": { "type": "string", "minLength": 1, "description": "Mount path inside the container.", "examples": [ "/workspace" ] }, "remove": { "type": "boolean", "description": "Removes the volume disk. Not supported yet: `remove: true` is\nrejected with 400.\n" } } }, "NetworkMountPatch": { "type": "object", "required": [ "volumeId" ], "additionalProperties": false, "description": "Mounts, moves, or unmounts one network volume. Mounting a volume the\npod does not have requires `path`.\n", "properties": { "volumeId": { "type": "string", "description": "ID of an existing NetworkVolume in the same data center as the pod.", "examples": [ "vol_xyz" ] }, "path": { "type": "string", "minLength": 1, "description": "Mount path inside the container. Required when mounting; optional when moving a mounted volume.", "examples": [ "/runpod-volume" ] }, "remove": { "type": "boolean", "description": "Unmount the volume. Cannot be combined with `path`." } } }, "GlobalMountPatch": { "type": "object", "required": [ "volumeId" ], "additionalProperties": false, "description": "Mounts, moves, or unmounts the pod's global volume.", "properties": { "volumeId": { "type": "string", "description": "ID of an existing GlobalVolume.", "examples": [ "gsb_abc" ] }, "path": { "type": "string", "minLength": 1, "description": "Mount path inside the container. Optional; when mounting, a default is chosen for you if omitted.", "examples": [ "/data" ] }, "remove": { "type": "boolean", "description": "Unmount the volume. Cannot be combined with `path`." } } }, "BaseGpuConfig": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "GPU type identifier", "examples": [ "NVIDIA GeForce RTX 4090" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 1024, "default": 1, "description": "Number of GPUs", "examples": [ 1 ] } } }, "GpuConfig": { "allOf": [ { "$ref": "#/components/schemas/BaseGpuConfig" }, { "type": "object", "required": [ "vcpuCount", "memory" ], "properties": { "vcpuCount": { "type": "number", "format": "double", "minimum": 1, "description": "Total vCPU count allocated to the pod across all requested GPUs.", "examples": [ 2 ] }, "memory": { "type": "number", "format": "double", "minimum": 1, "description": "Total system RAM in GB allocated to the pod across all requested GPUs.", "examples": [ 8 ] } } } ] }, "CreateGpuConfig": { "description": "GPU request for a pod create. Carries the CUDA host constraints, which\nlive here rather than at the body's top level so they are\nunrepresentable on a CPU pod.\n", "allOf": [ { "$ref": "#/components/schemas/BaseGpuConfig" }, { "type": "object", "properties": { "allowedCudaVersions": { "type": "array", "items": { "type": "string", "pattern": "^\\d+\\.\\d+$" }, "description": "Acceptable CUDA versions for the host machine, as `major.minor`.\nOmit to accept any version. Matching is exact, so a version no\nmachine reports yields a capacity error rather than a fallback —\ndiscover valid values per GPU type via\n`GET /v2/catalog/gpus?include=AVAILABILITY&product=POD`\n(`cudaVersions`).\n\nA non-empty set is mutually exclusive with minCudaVersion (400\nif both are sent). An explicit `[]` states no constraint, so it\nmay accompany a floor.\n", "examples": [ [ "12.8", "12.6" ] ] }, "minCudaVersion": { "type": "string", "pattern": "^\\d+\\.\\d+$", "description": "Lowest acceptable CUDA version for the host machine, as\n`major.minor`, compared numerically rather than as a decimal —\nso 12.11 is above 12.2. Use this for an open-ended floor and\nallowedCudaVersions for an exact set.\n\nMutually exclusive with a non-empty allowedCudaVersions (400 if\nboth are sent); an explicit `[]` there states no constraint and\nmay accompany this floor.\n", "examples": [ "12.1" ] }, "minRamPerGpu": { "type": "integer", "minimum": 1, "maximum": 65536, "description": "Minimum host system RAM in GB per requested GPU. This is a placement filter, not a resource request. The actual total allocated system RAM may be higher and is returned in gpu.memory.", "examples": [ 8 ] }, "minVcpuCountPerGpu": { "type": "integer", "minimum": 1, "maximum": 4096, "description": "Minimum host vCPU count per requested GPU. This is a placement filter, not a resource request. The actual total allocated vCPU count may be higher and is returned in gpu.vcpuCount.", "examples": [ 2 ] } } } ], "unevaluatedProperties": false }, "BaseCpuConfig": { "type": "object", "required": [ "id", "vcpuCount" ], "properties": { "id": { "type": "string", "description": "CPU flavor identifier, as returned by GET /v2/catalog/cpus.", "examples": [ "cpu5c" ], "minLength": 1 }, "vcpuCount": { "type": "integer", "minimum": 2, "description": "Number of vCPUs. Must be valid for the selected CPU flavor and must be a power of two.", "examples": [ 4 ] } } }, "CreateCpuConfig": { "allOf": [ { "$ref": "#/components/schemas/BaseCpuConfig" } ], "unevaluatedProperties": false }, "CpuConfig": { "allOf": [ { "$ref": "#/components/schemas/BaseCpuConfig" }, { "type": "object", "required": [ "memory" ], "properties": { "memory": { "type": "integer", "minimum": 1, "description": "Memory allocated to the pod in GB.", "examples": [ 16 ] } } } ] }, "FlashBoot": { "type": "string", "description": "FlashBoot cold-start acceleration mode.\n- `OFF` — disabled\n- `FLASHBOOT` — enabled\n- `PRIORITY_FLASHBOOT` — enabled with priority capacity\n", "enum": [ "OFF", "FLASHBOOT", "PRIORITY_FLASHBOOT" ] }, "EndpointType": { "type": "string", "description": "Request-routing semantics for a modern serverless endpoint.\n- `QUEUE` — submit asynchronous or synchronous jobs through the managed queue.\n- `LOAD_BALANCER` — send requests directly to worker-defined HTTP paths.\n Configure via `env`: `PORT` (server port, default 80), `PORT_HEALTH`\n (health-check port, default 80), and `HEALTH_CHECK_PATH` (path the\n load balancer polls for worker health, default `/ping`).\n", "x-enum-varnames": [ "EndpointTypeQueue", "EndpointTypeLoadBalancer" ], "enum": [ "QUEUE", "LOAD_BALANCER" ] }, "QueueBasedRequestUrls": { "type": "object", "additionalProperties": false, "required": [ "run", "runSync", "status", "stream", "cancel", "retry", "purgeQueue", "health" ], "properties": { "run": { "type": "string", "format": "uri", "description": "URL for asynchronously submitting a queued job.\nSee the [/run operation reference](https://docs.runpod.io/serverless/endpoints/operation-reference#/run) for request and response bodies.", "examples": [ "https://api.runpod.ai/v2/4m7x2k9q/run" ] }, "runSync": { "type": "string", "format": "uri", "description": "URL for synchronously submitting a queued job. Accepts an optional `?wait=x` query parameter to control how long the request waits for job completion, defaulting to 90 seconds.\nSee the [/runsync operation reference](https://docs.runpod.io/serverless/endpoints/operation-reference#/runsync) for request and response bodies.", "examples": [ "https://api.runpod.ai/v2/4m7x2k9q/runsync" ] }, "status": { "type": "string", "format": "uri", "description": "Check the current state, execution statistics, and results of a previously submitted job.\nSee the [/status operation reference](https://docs.runpod.io/serverless/endpoints/operation-reference#/status) for request and response bodies.", "examples": [ "https://api.runpod.ai/v2/4m7x2k9q/status/{job_id}" ] }, "stream": { "type": "string", "format": "uri", "description": "Receive incremental results as they become available from a job that generates output progressively.\nSee the [/stream operation reference](https://docs.runpod.io/serverless/endpoints/operation-reference#/stream) for request and response bodies.", "examples": [ "https://api.runpod.ai/v2/4m7x2k9q/stream/{job_id}" ] }, "cancel": { "type": "string", "format": "uri", "description": "Stop an in-progress job or remove a queued job before it starts.\nSee the [/cancel operation reference](https://docs.runpod.io/serverless/endpoints/operation-reference#/cancel) for request and response bodies.", "examples": [ "https://api.runpod.ai/v2/4m7x2k9q/cancel/{job_id}" ] }, "retry": { "type": "string", "format": "uri", "description": "Requeue a failed or timed-out job without submitting a new request.\nSee the [/retry operation reference](https://docs.runpod.io/serverless/endpoints/operation-reference#/retry) for request and response bodies.", "examples": [ "https://api.runpod.ai/v2/4m7x2k9q/retry/{job_id}" ] }, "purgeQueue": { "type": "string", "format": "uri", "description": "Remove all pending jobs from the queue. Does not affect in-progress jobs.\nSee the [/purge-queue operation reference](https://docs.runpod.io/serverless/endpoints/operation-reference#/purge-queue) for request and response bodies.", "examples": [ "https://api.runpod.ai/v2/4m7x2k9q/purge-queue" ] }, "health": { "type": "string", "format": "uri", "description": "Overview of an endpoint's operational status.\nSee the [/health operation reference](https://docs.runpod.io/serverless/endpoints/operation-reference#/health) for request and response bodies.", "examples": [ "https://api.runpod.ai/v2/4m7x2k9q/health" ] } } }, "LoadBalancingRequestUrls": { "type": "object", "additionalProperties": false, "required": [ "base", "health" ], "properties": { "base": { "type": "string", "format": "uri", "description": "Base URL for worker-defined HTTP and WebSocket paths.\nSee [Load balancing endpoints](https://docs.runpod.io/serverless/load-balancing/overview).", "examples": [ "https://4m7x2k9q.api.runpod.ai" ] }, "health": { "type": "string", "format": "uri", "description": "Health check endpoint the load balancer will periodically ping to decide if the worker is healthy enough to receive traffic. Configurable by setting the `HEALTH_CHECK_PATH` environment variable. Defaults to `/ping` if the variable is not set.\nSee [Health checks](https://docs.runpod.io/serverless/load-balancing/overview#health-checks) for the response codes it interprets.", "examples": [ "https://4m7x2k9q.api.runpod.ai/ping" ] } } }, "EndpointRequestUrls": { "description": "Request URLs appropriate to the endpoint's top-level `type`.\nQueue-based endpoints provide job submission and management URLs;\nload-balancing endpoints provide `base` and `health` because their\nremaining paths are worker-defined.\n\nRequest and response bodies for the queue-based URLs are documented in\nthe [serverless operation reference](https://docs.runpod.io/serverless/endpoints/operation-reference).\nLoad-balancing endpoints are documented in\n[Load balancing endpoints](https://docs.runpod.io/serverless/load-balancing/overview).", "oneOf": [ { "$ref": "#/components/schemas/QueueBasedRequestUrls" }, { "$ref": "#/components/schemas/LoadBalancingRequestUrls" } ] }, "BaseEndpointGpuConfig": { "type": "object", "properties": { "pools": { "type": "array", "minItems": 1, "description": "Serverless GPU pool IDs (as returned by `GET /v2/catalog/gpus` in\n`pool`). Workers are placed on whichever listed pool has capacity.\nNarrow a pool down to specific cards with `excludedTypes`.\n\nOn `PATCH`, `pools` and `excludedTypes` are one selection and are\nreplaced together, so sending `pools` by itself **clears the\nexclusions**. Two cases:\n\n- **Changing pools, keeping exclusions** — send both fields in one\n request: `{\"gpu\": {\"pools\": [\"ADA_24\"], \"excludedTypes\":\n [\"NVIDIA L40\"]}}`. `GET` the endpoint first to read the current\n `excludedTypes` and resend the ones that still apply to the new\n pools; an exclusion naming a type outside `pools` is a 400.\n- **Changing only `count` or a CUDA constraint** — omit `pools`:\n `{\"gpu\": {\"minCudaVersion\": \"12.4\"}}`. The pool list and the\n exclusions are both left exactly as they are.\n\n`excludedTypes` documents the full rule.\n", "items": { "type": "string" }, "examples": [ [ "ADA_24" ] ] }, "excludedTypes": { "type": "array", "uniqueItems": true, "description": "GPU **type** IDs to subtract from the selected pools — the `id`\nfield of `GET /v2/catalog/gpus`, the same identifiers pods take in\n`gpu.id`. Workers run on every type in `pools` except these. Omit to\nuse the whole pool.\n\nPools stay the unit of selection; types are the unit of\nsubtraction. There is no inclusive allowlist: a card later added to\none of your pools becomes eligible, which is the honest reading of\n\"this pool, minus these\".\n\nTied to `pools`, because the two together are one selection:\nsupplying `pools` replaces that selection wholesale, so a `PATCH`\nsending `pools` **without `excludedTypes`** **clears** them —\nrestate them to keep them. A `PATCH` that omits `pools` leaves both\nthe pools and the exclusions untouched, so changing only a CUDA\nconstraint cannot widen a pinned endpoint.\n\nRejected with 400 if a value is not a GPU type in one of `pools`,\nso a typo cannot produce a filter that does nothing. Surrounding whitespace\nis trimmed, so `\" NVIDIA L40\"` and `\"NVIDIA L40\"` mean the same card.\n", "items": { "type": "string", "pattern": "^\\s*[^-\\s]" }, "examples": [ [ "NVIDIA L40" ] ] }, "count": { "type": "integer", "minimum": 1, "default": 1, "description": "GPUs per worker", "examples": [ 1 ] } } }, "EndpointGpuConfig": { "allOf": [ { "$ref": "#/components/schemas/BaseEndpointGpuConfig" }, { "type": "object", "required": [ "pools", "allowedCudaVersions", "minCudaVersion" ], "properties": { "allowedCudaVersions": { "type": "array", "items": { "type": "string" }, "description": "Acceptable CUDA versions for worker placement, as `major.minor`. Empty means any version.", "examples": [ [] ] }, "minCudaVersion": { "type": [ "string", "null" ], "description": "Lowest acceptable CUDA version for worker placement, as `major.minor`. Null means no floor.", "examples": [ null ] } } } ] }, "CreateEndpointGpuConfig": { "description": "GPU request for an endpoint create. Carries the CUDA constraints, which\nlive here rather than at the body's top level so they are\nunrepresentable on a CPU endpoint.\n", "allOf": [ { "$ref": "#/components/schemas/BaseEndpointGpuConfig" }, { "type": "object", "required": [ "pools" ], "properties": { "allowedCudaVersions": { "type": "array", "items": { "type": "string", "pattern": "^\\d+\\.\\d+$" }, "description": "Acceptable CUDA versions for worker placement, as\n`major.minor`. Omit to accept any version (or inherit the\ntemplate's constraint when creating from `templateId`).\nMatching is exact — discover valid values per GPU type via\n`GET /v2/catalog/gpus?include=AVAILABILITY&product=SERVERLESS`\n(`cudaVersions`).\n\nA non-empty set is mutually exclusive with minCudaVersion (400\nif both are sent). An explicit `[]` states no constraint, so it\nmay accompany a floor.\n", "examples": [ [ "12.8", "12.6" ] ] }, "minCudaVersion": { "type": "string", "pattern": "^\\d+\\.\\d+$", "description": "Lowest acceptable CUDA version for worker placement, as\n`major.minor`, compared numerically rather than as a decimal —\nso 12.11 is above 12.2. Use this for an open-ended floor and\nallowedCudaVersions for an exact set.\n\nMutually exclusive with a non-empty allowedCudaVersions (400 if\nboth are sent); an explicit `[]` there states no constraint and\nmay accompany this floor.\n", "examples": [ "12.1" ] } } } ], "unevaluatedProperties": false }, "UpdateEndpointGpuConfig": { "description": "Partial GPU update — every field is optional and an omitted one is left\nunchanged. Unlike create, `pools` is optional, so changing only a CUDA\nconstraint does not require resending the pool list.\n\n`excludedTypes` requires `pools`, because the two are one selection and\nonly a supplied `pools` replaces it — an exclusion on its own would\notherwise be silently dropped.\n", "allOf": [ { "$ref": "#/components/schemas/BaseEndpointGpuConfig" }, { "type": "object", "dependentRequired": { "excludedTypes": [ "pools" ] }, "properties": { "allowedCudaVersions": { "type": "array", "items": { "type": "string", "pattern": "^\\d+\\.\\d+$" }, "description": "Acceptable CUDA versions for worker placement, as\n`major.minor`. An explicit `[]` clears the constraint;\nomitting the field leaves it unchanged. Takes effect as\nworkers are replaced.\n\nA non-empty set is mutually exclusive with minCudaVersion (400\nif both are sent). An explicit `[]` states no constraint, so it\nmay accompany a floor.\nSetting one does not clear the other — clear it explicitly in\nthe same patch if the endpoint already carries it.\n" }, "minCudaVersion": { "type": "string", "pattern": "^$|^\\d+\\.\\d+$", "description": "Lowest acceptable CUDA version for worker placement, as\n`major.minor`. An explicit `\"\"` clears the floor; omitting the\nfield leaves it unchanged. Takes effect as workers are\nreplaced.\n\nMutually exclusive with a non-empty allowedCudaVersions (400 if\nboth are sent); an explicit `[]` there states no constraint and\nmay accompany this floor.\n", "examples": [ "12.1" ] } } } ], "unevaluatedProperties": false }, "EndpointWorkers": { "type": "object", "additionalProperties": false, "properties": { "min": { "type": "integer", "minimum": 0, "description": "Minimum number of workers.", "examples": [ 0 ] }, "max": { "type": "integer", "minimum": 0, "description": "Maximum number of workers.", "examples": [ 5 ] }, "idleTimeout": { "type": "integer", "minimum": 1, "maximum": 3600, "description": "Seconds before idle workers scale down. Not applicable to queue-based\nendpoints scaling on `requestCount` — rejected on create/update and\nomitted from responses for that combination.\n", "examples": [ 5 ] }, "initTimeout": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 14400, "x-go-type": "nullable.Nullable[int]", "x-go-type-import": { "path": "github.com/oapi-codegen/nullable" }, "x-go-type-skip-optional-pointer": true, "description": "Seconds a worker may take to become ready before it is terminated\nand replaced. In responses, the endpoint setting, or null if none is\nset. In PATCH, null clears the endpoint setting so the platform\ndefault applies. Changes apply to workers that start initializing\nafter the change and do not trigger a rollout.\n", "examples": [ 1800 ] } } }, "QueueDelayScaling": { "type": "object", "additionalProperties": false, "description": "Scale on queue wait time. Queue-based endpoints only.", "required": [ "type", "queueDelay" ], "properties": { "type": { "type": "string", "description": "Scaler discriminator. Always `QUEUE_DELAY` for this variant.", "enum": [ "QUEUE_DELAY" ] }, "queueDelay": { "type": "number", "format": "float", "minimum": 0.5, "description": "Adjusts the number of workers based on how long requests wait in the queue.", "examples": [ 4 ] } } }, "RequestCountScaling": { "type": "object", "additionalProperties": false, "description": "Scale on concurrent in-flight requests per worker. Required for\nload-balancing endpoints; also selectable for queue-based.\n", "required": [ "type", "requestCount" ], "properties": { "type": { "type": "string", "description": "Scaler discriminator. Always `REQUEST_COUNT` for this variant.", "enum": [ "REQUEST_COUNT" ] }, "requestCount": { "type": "integer", "minimum": 1, "description": "Adjusts the number of workers based on active in-flight requests.", "examples": [ 4 ] } } }, "EndpointScaling": { "description": "Autoscaling signal — a discriminated union on `type`: `QUEUE_DELAY`\n(queue-based endpoints only) or `REQUEST_COUNT`. The scaler is chosen\nindependently of the endpoint's routing `type` and can be switched on\nupdate.\n", "oneOf": [ { "$ref": "#/components/schemas/QueueDelayScaling" }, { "$ref": "#/components/schemas/RequestCountScaling" } ], "discriminator": { "propertyName": "type", "mapping": { "QUEUE_DELAY": "#/components/schemas/QueueDelayScaling", "REQUEST_COUNT": "#/components/schemas/RequestCountScaling" } } }, "Endpoint": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "type": "object", "required": [ "id", "name", "workers", "scaling", "dataCenterIds", "networkVolumes", "mounts", "timeout", "flashboot", "createdAt" ], "properties": { "costCenter": { "$ref": "#/components/schemas/ResourceCostCenter" }, "tags": { "$ref": "#/components/schemas/ResourceTags" }, "id": { "type": "string", "examples": [ "ep_abc123" ] }, "name": { "type": "string", "examples": [ "my-inference" ] }, "type": { "$ref": "#/components/schemas/EndpointType" }, "requestUrls": { "$ref": "#/components/schemas/EndpointRequestUrls" }, "gpu": { "anyOf": [ { "$ref": "#/components/schemas/EndpointGpuConfig" }, { "type": "null" } ] }, "cpu": { "type": "array", "minItems": 1, "description": "Eligible CPU configurations for each worker, in the order they\nwere submitted. Present for CPU endpoints and omitted for GPU\nendpoints. Memory is derived from the selected flavor's catalog\nRAM multiplier.\n", "items": { "$ref": "#/components/schemas/CpuConfig" } }, "workers": { "allOf": [ { "$ref": "#/components/schemas/EndpointWorkers" } ], "required": [ "min", "max", "initTimeout" ] }, "scaling": { "$ref": "#/components/schemas/EndpointScaling" }, "dataCenterIds": { "type": "array", "items": { "type": "string" }, "examples": [ [ "US-TX-3" ] ] }, "networkVolumes": { "type": "array", "items": { "type": "string" }, "deprecated": true, "examples": [ [ "vol_abc" ] ] }, "mounts": { "$ref": "#/components/schemas/EndpointMounts" }, "timeout": { "type": "integer", "description": "Per-request execution timeout in milliseconds", "examples": [ 300000 ] }, "flashboot": { "$ref": "#/components/schemas/FlashBoot" }, "createdAt": { "type": "string", "format": "date-time", "examples": [ "2026-03-13T20:00:00Z" ] }, "userId": { "type": [ "string", "null" ], "description": "ID of the account the endpoint is stamped to. This is its\ncreator, unless the endpoint was migrated from a team. Omitted\nwhen unknown.\n", "examples": [ "user_abc123" ] }, "version": { "type": [ "integer", "null" ], "description": "The endpoint's current worker configuration version. To see\nwhether a worker runs an older configuration, use its\n`isStale`: comparing versions directly can disagree on legacy\nendpoints (version 1). It changes on edits that roll out new\nworkers (image, template, compute, volumes, CUDA versions,\ndata centers) and not on scaling, worker count or timeout\nedits. Omitted when unknown.\n", "examples": [ 4 ] } } } ] }, "ListEndpointsResponse": { "type": "object", "required": [ "endpoints", "pagination" ], "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "WorkerStatus": { "type": "string", "description": "Derived worker state, reconciled from the worker pod's lifecycle status\nand the live job-queue view.\n- `RUNNING` — actively processing a job\n- `IDLE` — ready and polling for jobs\n- `INITIALIZING` — starting up, not yet ready\n- `THROTTLED` — waiting on compute capacity\n- `UNHEALTHY` — failing health checks\n", "x-enum-varnames": [ "WorkerStatusRunning", "WorkerStatusIdle", "WorkerStatusInitializing", "WorkerStatusThrottled", "WorkerStatusUnhealthy" ], "enum": [ "RUNNING", "IDLE", "INITIALIZING", "THROTTLED", "UNHEALTHY" ] }, "Worker": { "type": "object", "required": [ "id", "status", "gpuCount", "isStale" ], "properties": { "id": { "type": "string", "description": "Identifier of the pod backing this worker. Each worker is one pod,\nso there is no separate pod identifier.\n", "examples": [ "worker_abc" ] }, "status": { "$ref": "#/components/schemas/WorkerStatus" }, "isStale": { "type": "boolean", "description": "True when the worker is running an older endpoint configuration than\nthe current one (e.g. mid rolling-update). This is the authoritative\nflag: it is derived from `version` vs the response's `endpointVersion`,\nexcept on legacy endpoints (`endpointVersion` 1) where it falls back\nto a container-image comparison.\n", "examples": [ false ] }, "version": { "type": [ "integer", "null" ], "description": "Endpoint configuration version this worker is running. Compare with\nthe response's `endpointVersion`. Null if unknown.\n", "examples": [ 4 ] }, "gpuCount": { "type": "integer", "minimum": 0, "description": "GPUs allocated to the worker.", "examples": [ 1 ] }, "image": { "type": [ "string", "null" ], "description": "Container image the worker is running.", "examples": [ "my-org/sdxl-worker:latest" ] }, "uptimeSeconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Seconds the worker has been running. Null until the worker is placed and running.", "examples": [ 3600 ] }, "gpuTypeId": { "type": [ "string", "null" ], "description": "GPU type the worker is placed on. Null until the worker is placed.", "examples": [ "NVIDIA RTX 4090" ] }, "dataCenterId": { "type": [ "string", "null" ], "description": "Data center the worker is placed in. Null until the worker is placed.", "examples": [ "US-TX-3" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the worker last started. Null if it has not started.", "examples": [ "2026-03-26T00:00:00Z" ] } } }, "WorkerSummary": { "type": "object", "description": "Histogram of the returned workers by status. The per-status counts are a\nroll-up of the `workers` array, so `running + idle + initializing +\nthrottled + unhealthy == total == len(workers)`.\n", "required": [ "running", "idle", "initializing", "throttled", "unhealthy", "total" ], "properties": { "running": { "type": "integer", "minimum": 0, "description": "Workers actively processing a job.", "examples": [ 2 ] }, "idle": { "type": "integer", "minimum": 0, "description": "Ready workers polling for jobs.", "examples": [ 1 ] }, "initializing": { "type": "integer", "minimum": 0, "description": "Workers starting up, not yet ready.", "examples": [ 0 ] }, "throttled": { "type": "integer", "minimum": 0, "description": "Workers waiting on compute capacity.", "examples": [ 0 ] }, "unhealthy": { "type": "integer", "minimum": 0, "description": "Workers failing health checks.", "examples": [ 0 ] }, "total": { "type": "integer", "minimum": 0, "description": "All workers currently allocated to the endpoint.", "examples": [ 3 ] } } }, "EndpointMetricsInterval": { "type": "string", "enum": [ "1m", "5m", "15m", "30m", "1h", "6h", "12h", "1d" ], "default": "1h", "description": "Bucket size for endpoint metrics." }, "EndpointDurationStats": { "type": "object", "description": "Millisecond statistics over one bucket.", "required": [ "min", "max", "total", "p70", "p90", "p95", "p98" ], "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "total": { "type": "number", "format": "double", "description": "Sum over every request (or cold start) in the bucket." }, "p70": { "type": "integer" }, "p90": { "type": "integer" }, "p95": { "type": "integer" }, "p98": { "type": "integer" } } }, "EndpointRequestMetric": { "type": "object", "required": [ "time", "requests", "completed", "failed", "retries", "executionTimeMs", "delayTimeMs" ], "properties": { "time": { "type": "string", "format": "date-time", "description": "Bucket start (UTC)." }, "requests": { "type": "integer", "description": "Requests that finished in this bucket." }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "retries": { "type": "integer" }, "executionTimeMs": { "$ref": "#/components/schemas/EndpointDurationStats" }, "delayTimeMs": { "$ref": "#/components/schemas/EndpointDurationStats" } } }, "EndpointColdStartMetric": { "type": "object", "required": [ "time", "count", "durationMs" ], "properties": { "time": { "type": "string", "format": "date-time", "description": "Bucket start (UTC)." }, "count": { "type": "integer" }, "durationMs": { "$ref": "#/components/schemas/EndpointDurationStats" } } }, "EndpointWorkerMetric": { "type": "object", "required": [ "time", "running", "idle", "initializing", "throttled", "unhealthy" ], "properties": { "time": { "type": "string", "format": "date-time", "description": "Bucket start (UTC)." }, "running": { "type": "integer" }, "idle": { "type": "integer" }, "initializing": { "type": "integer" }, "throttled": { "type": "integer" }, "unhealthy": { "type": "integer" } } }, "EndpointRequestMetricsResponse": { "type": "object", "description": "Request counts and durations per bucket for the resolved window. `records` contains only buckets with activity. Buckets with no activity are omitted, not zero-filled, so `records` can be shorter than the number of buckets in the window, or empty. Results are paged: see `pagination`.\n", "required": [ "startTime", "endTime", "interval", "records", "pagination" ], "properties": { "startTime": { "type": "string", "format": "date-time", "description": "Resolved window start (after defaults)." }, "endTime": { "type": "string", "format": "date-time", "description": "Resolved window end (after defaults and the clamp to now)." }, "interval": { "$ref": "#/components/schemas/EndpointMetricsInterval" }, "records": { "type": "array", "description": "This page's buckets, oldest first.", "items": { "$ref": "#/components/schemas/EndpointRequestMetric" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "EndpointColdStartMetricsResponse": { "type": "object", "description": "Cold start counts and durations per bucket for the resolved window. `records` contains only buckets with activity. Buckets with no activity are omitted, not zero-filled, so `records` can be shorter than the number of buckets in the window, or empty. Results are paged: see `pagination`.\n", "required": [ "startTime", "endTime", "interval", "records", "pagination" ], "properties": { "startTime": { "type": "string", "format": "date-time", "description": "Resolved window start (after defaults)." }, "endTime": { "type": "string", "format": "date-time", "description": "Resolved window end (after defaults and the clamp to now)." }, "interval": { "$ref": "#/components/schemas/EndpointMetricsInterval" }, "records": { "type": "array", "description": "This page's buckets, oldest first.", "items": { "$ref": "#/components/schemas/EndpointColdStartMetric" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "EndpointWorkerMetricsResponse": { "type": "object", "description": "Worker counts by state per bucket for the resolved window. `records` contains only buckets with activity. Buckets with no activity are omitted, not zero-filled, so `records` can be shorter than the number of buckets in the window, or empty. Results are paged: see `pagination`.\n", "required": [ "startTime", "endTime", "interval", "records", "pagination" ], "properties": { "startTime": { "type": "string", "format": "date-time", "description": "Resolved window start (after defaults)." }, "endTime": { "type": "string", "format": "date-time", "description": "Resolved window end (after defaults and the clamp to now)." }, "interval": { "$ref": "#/components/schemas/EndpointMetricsInterval" }, "records": { "type": "array", "description": "This page's buckets, oldest first.", "items": { "$ref": "#/components/schemas/EndpointWorkerMetric" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ListEndpointWorkersResponse": { "type": "object", "required": [ "workers", "summary" ], "properties": { "workers": { "type": "array", "items": { "$ref": "#/components/schemas/Worker" } }, "summary": { "$ref": "#/components/schemas/WorkerSummary" }, "endpointVersion": { "type": [ "integer", "null" ], "description": "The endpoint's current configuration version. A worker whose\n`version` differs is running stale config (see `worker.isStale`).\nNull if unknown.\n", "examples": [ 4 ] } } }, "ReleaseSource": { "type": "string", "description": "What produced the release.\n- `GIT_BUILD` — a completed GitHub build (see `buildId`)\n- `MANUAL` — a manual configuration change\n", "x-enum-varnames": [ "ReleaseSourceGitBuild", "ReleaseSourceManual" ], "enum": [ "GIT_BUILD", "MANUAL" ] }, "BuildState": { "type": "string", "description": "GitHub build lifecycle state. `COMPLETED`, `FAILED`, `CANCELLED`, and\n`TEST_FAILED` are terminal; `PENDING`, `BUILDING`, `UPLOADING`, and\n`TESTING` are live.\n", "x-enum-varnames": [ "BuildStatePending", "BuildStateBuilding", "BuildStateUploading", "BuildStateTesting", "BuildStateCompleted", "BuildStateFailed", "BuildStateCancelled", "BuildStateTestFailed" ], "enum": [ "PENDING", "BUILDING", "UPLOADING", "TESTING", "COMPLETED", "FAILED", "CANCELLED", "TEST_FAILED" ] }, "Build": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "examples": [ "build_abc123" ] }, "status": { "$ref": "#/components/schemas/BuildState" }, "commitHash": { "type": [ "string", "null" ], "description": "Short hash of the commit that triggered the build.", "examples": [ "abc1234" ] }, "commitMessage": { "type": [ "string", "null" ], "examples": [ "bump model" ] }, "branch": { "type": [ "string", "null" ], "description": "Git branch the commit was pushed to.", "examples": [ "main" ] }, "commitDate": { "type": [ "string", "null" ], "format": "date-time", "description": "When the triggering commit was authored.", "examples": [ "2026-06-01T12:00:00Z" ] }, "imageName": { "type": [ "string", "null" ], "description": "Fully qualified image the build produced (or will produce).", "examples": [ "registry.runpod.net/repo:abc1234" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the build started. Null while the build is still pending.", "examples": [ "2026-06-01T12:00:05Z" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the build reached a terminal state. Null while the build is live.", "examples": [ "2026-06-01T12:04:31Z" ] }, "error": { "type": [ "string", "null" ], "description": "Failure detail for `FAILED` / `TEST_FAILED` builds; null otherwise." } } }, "ListEndpointBuildsResponse": { "type": "object", "required": [ "builds", "pagination" ], "properties": { "builds": { "type": "array", "description": "Build history, newest first, cursor-paginated (an omitted `limit`\ndefaults to 100). Page with `cursor`/`limit` to walk the full\nhistory, or fetch any build by id via\n`GET /v2/serverless/{id}/builds/{buildId}`.\n", "items": { "$ref": "#/components/schemas/Build" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ReleaseDiffEntry": { "type": "object", "required": [ "field", "old", "new" ], "properties": { "field": { "type": "string", "description": "The changed configuration field. Top-level (e.g. `gpuCount`,\n`locations`) or template-scoped (e.g. `template.imageName`,\n`template.env`).\n", "examples": [ "template.imageName" ] }, "old": { "description": "Previous value, as raw JSON. Null when the field was added." }, "new": { "description": "New value, as raw JSON. Null when the field was removed." } } }, "Release": { "type": "object", "required": [ "id", "source", "createdAt", "workerCount", "diff" ], "properties": { "id": { "type": "string", "examples": [ "rel_abc123" ] }, "version": { "type": [ "integer", "null" ], "description": "The endpoint configuration version this release produced.", "examples": [ 4 ] }, "source": { "$ref": "#/components/schemas/ReleaseSource" }, "buildId": { "type": [ "string", "null" ], "description": "The GitHub build that produced this release. Set when `source` is\n`GIT_BUILD`; null for `MANUAL` releases. Fetch build detail/logs via\n`/v2/serverless/{id}/builds/{buildId}`.\n", "examples": [ "build_abc123" ] }, "createdByUserId": { "type": [ "string", "null" ], "description": "ID of the user who created the release." }, "workerCount": { "type": "integer", "minimum": 0, "description": "Workers currently running this release's version.", "examples": [ 2 ] }, "createdAt": { "type": "string", "format": "date-time", "examples": [ "2026-03-13T20:00:00Z" ] }, "diff": { "type": "array", "description": "Configuration fields that changed in this release.", "items": { "$ref": "#/components/schemas/ReleaseDiffEntry" } } } }, "RolloutSummary": { "type": "object", "required": [ "inProgress", "workersOnLatest", "workersTotal", "percentOnLatest" ], "properties": { "inProgress": { "type": "boolean", "description": "True while any worker is still running an older version.", "examples": [ true ] }, "workersOnLatest": { "type": "integer", "minimum": 0, "description": "Workers running the endpoint's current version.", "examples": [ 2 ] }, "workersTotal": { "type": "integer", "minimum": 0, "description": "All workers currently allocated to the endpoint.", "examples": [ 3 ] }, "percentOnLatest": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Percentage of workers on the current version (0 when there are no workers).", "examples": [ 67 ] } } }, "ListEndpointReleasesResponse": { "type": "object", "required": [ "rollout", "releases", "pagination" ], "properties": { "endpointVersion": { "type": [ "integer", "null" ], "description": "The endpoint's current configuration version. Null if unknown.", "examples": [ 4 ] }, "rollout": { "$ref": "#/components/schemas/RolloutSummary" }, "releases": { "type": "array", "description": "Release history, newest first.", "items": { "$ref": "#/components/schemas/Release" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "CreateEndpointRequest": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "if": { "not": { "required": [ "templateId" ] } }, "then": { "required": [ "image" ] } }, { "type": "object", "required": [ "name", "type", "scaling" ], "properties": { "gpu": { "$ref": "#/components/schemas/CreateEndpointGpuConfig" }, "name": { "type": "string", "minLength": 1, "examples": [ "my-inference" ] }, "scaling": { "$ref": "#/components/schemas/EndpointScaling" }, "type": { "allOf": [ { "$ref": "#/components/schemas/EndpointType" } ], "description": "Request-routing model. Required — it determines the valid scaler\nand request URLs, so it must be chosen explicitly on every create.\n" }, "cpu": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Eligible CPU configurations for each worker. Memory is derived from the\nselected flavor's catalog RAM multiplier. Exact duplicate configurations\nare rejected; the same flavor may be listed at different vCPU counts.\n", "items": { "$ref": "#/components/schemas/CreateCpuConfig" } }, "dataCenterIds": { "type": "array", "items": { "type": "string" }, "description": "Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose." }, "flashboot": { "allOf": [ { "$ref": "#/components/schemas/FlashBoot" } ], "default": "OFF" }, "networkVolumes": { "type": "array", "items": { "type": "string" }, "description": "Network volume IDs.", "deprecated": true }, "mounts": { "$ref": "#/components/schemas/EndpointMountsInput" }, "templateId": { "type": "string", "minLength": 1, "description": "ID of a serverless template to base this endpoint on. The\ntemplate is resolved at create time into the same container\nsettings you could otherwise spread into this body (image,\nargs, disk, ports, env, registry); explicit body fields\noverride the template's, except `env`, which is merged per\nkey with body values winning. The template's\nallowedCudaVersions seeds `gpu.allowedCudaVersions` when the\nbody omits it — but only for a GPU create, since a CPU endpoint\nhas no gpu block to seed into, and not when the body sets\n`gpu.minCudaVersion`, since seeding a set beside a floor would\nmanufacture the mutual-exclusion 400 from a valid request. Its\npod-specific startSsh/startJupyter flags are\nignored. Later template edits do not affect the endpoint.\nThe template may be one of your own or a public catalog\ntemplate — see `GET /v2/catalog/templates` (unknown or\ninaccessible ID → 404) — and must be a serverless template\n(→ 422).\n", "examples": [ "30zmvf89kd" ] }, "timeout": { "type": "integer", "default": 300000 }, "workers": { "allOf": [ { "$ref": "#/components/schemas/EndpointWorkers" } ], "properties": { "min": { "type": "integer", "default": 0 }, "max": { "type": "integer", "default": 3 }, "idleTimeout": { "type": "integer", "default": 10 } } } } } ], "unevaluatedProperties": false, "if": { "required": [ "type" ], "properties": { "type": { "const": "LOAD_BALANCER" } } }, "then": { "properties": { "scaling": { "$ref": "#/components/schemas/RequestCountScaling" } } } }, "UpdateEndpointRequest": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "type": "object", "description": "Only provided fields are changed.", "properties": { "cpu": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Complete replacement CPU selection. Valid only for an existing CPU\nendpoint; endpoint compute family cannot be changed.\n", "items": { "$ref": "#/components/schemas/CreateCpuConfig" } }, "dataCenterIds": { "type": "array", "items": { "type": "string" }, "description": "Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose." }, "flashboot": { "$ref": "#/components/schemas/FlashBoot" }, "gpu": { "$ref": "#/components/schemas/UpdateEndpointGpuConfig" }, "name": { "type": "string", "minLength": 1 }, "networkVolumes": { "type": "array", "items": { "type": "string" }, "description": "Network volume IDs. Pass `[]` to detach.", "deprecated": true }, "mounts": { "$ref": "#/components/schemas/EndpointMountsInput" }, "scaling": { "$ref": "#/components/schemas/EndpointScaling" }, "templateId": { "type": "string", "description": "ID of a serverless template whose container settings are\napplied as if they were provided in this PATCH body (image,\nargs, disk, ports, env, registry). Explicit body fields\noverride the template's; `env` merges template and body per\nkey (body wins) and, per PATCH semantics, replaces the\nendpoint's env. One-time application — no link to the\ntemplate is retained. Must be one of your templates or a\npublic template (unknown or inaccessible ID → 404); must be\na serverless template (→ 422).\n", "examples": [ "30zmvf89kd" ] }, "timeout": { "type": "integer" }, "workers": { "$ref": "#/components/schemas/EndpointWorkers" } } } ], "unevaluatedProperties": false }, "Utilization": { "type": "object", "description": "Single-value utilization percentage (0–100). Shared by `cpu` and `memory`.", "properties": { "util": { "type": "integer", "examples": [ 45 ] } } }, "PodGpuUtilization": { "type": "object", "description": "Per-GPU utilization metrics.", "properties": { "util": { "type": "integer", "examples": [ 94 ] }, "memoryUtil": { "type": "integer", "examples": [ 78 ] } } }, "PodRuntimePort": { "type": "object", "description": "Live port mapping for a running pod.", "properties": { "private": { "type": "integer", "examples": [ 8888 ] }, "public": { "type": [ "integer", "null" ], "examples": [ 43210 ] }, "type": { "type": "string", "examples": [ "http" ] }, "ip": { "type": [ "string", "null" ], "examples": [ "45.23.12.1" ] } } }, "PodRuntime": { "type": "object", "description": "Live utilization metrics for a running pod.", "properties": { "uptime": { "type": "integer", "description": "Seconds since the container started", "examples": [ 3600 ] }, "gpus": { "type": "array", "items": { "$ref": "#/components/schemas/PodGpuUtilization" } }, "cpu": { "$ref": "#/components/schemas/Utilization" }, "memory": { "$ref": "#/components/schemas/Utilization" }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/PodRuntimePort" } } } }, "PodStatus": { "type": "string", "description": "Lifecycle status of a pod.\n- `PROVISIONING` — pod is being allocated\n- `STARTING` — container is starting\n- `RUNNING` — container is healthy\n- `EXITED` — container exited (stopped)\n- `ERROR` — container is in an unrecoverable error state\n- `TERMINATED` — pod has been permanently deleted\n", "enum": [ "PROVISIONING", "STARTING", "RUNNING", "EXITED", "ERROR", "TERMINATED" ] }, "PodAction": { "type": "string", "description": "State transition to trigger on a pod.", "enum": [ "start", "stop", "restart", "terminate" ] }, "LogSource": { "type": "string", "description": "Log source to include in a log stream.\n- `container` — container stdout/stderr log stream\n- `system` — host lifecycle/userlogs stream\n", "x-enum-varnames": [ "LogSourceContainer", "LogSourceSystem" ], "enum": [ "container", "system" ] }, "Cloud": { "type": "string", "description": "Cloud tier.\n- `SECURE` — Runpod-owned datacenter hardware\n- `COMMUNITY` — community-hosted hardware\n", "enum": [ "SECURE", "COMMUNITY" ] }, "TemplateCategory": { "type": "string", "description": "Controls how the template is grouped and filtered in the Runpod console.\nIt does not affect hardware selection, scheduling, or billing.\n- `CPU` — CPU-only workloads\n- `NVIDIA` — NVIDIA GPU workloads\n- `AMD` — AMD GPU workloads\n", "enum": [ "CPU", "NVIDIA", "AMD" ] }, "PodGlobalNetworking": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether global networking is enabled, giving the pod a private IP reachable across data centers. Derived from whether the pod has an assigned global-network address.", "examples": [ true ] }, "ip": { "type": "string", "description": "The pod's assigned global-networking IP. Present only when enabled.", "examples": [ "10.65.1.42" ] }, "internalDns": { "type": "string", "description": "Internal DNS name (`.runpod.internal`), reachable from other globally-networked pods in the same account. Present only when enabled.", "examples": [ "gfj8b292vyg08g.runpod.internal" ] } } }, "PodSshEndpoint": { "type": "object", "required": [ "host", "port", "username", "command" ], "description": "One way to reach the pod over SSH, as both its parts and a ready-to-run invocation.", "properties": { "host": { "type": "string", "description": "Hostname or IP to connect to.", "examples": [ "ssh.runpod.io" ] }, "port": { "type": "integer", "description": "TCP port to connect to.", "examples": [ 22 ] }, "username": { "type": "string", "description": "SSH username. For the proxy this is an opaque routing token, not a user account on the pod.", "examples": [ "7h9k2m4n6p-64411eb2" ] }, "command": { "type": "string", "description": "The equivalent `ssh` invocation, ready to run. Add `-i ` if the matching private key is not one of your default identities, and `-o StrictHostKeyChecking=no` to skip the host-key prompt on short-lived pods.", "examples": [ "ssh 7h9k2m4n6p-64411eb2@ssh.runpod.io" ] } } }, "PodSsh": { "type": "object", "required": [ "proxy", "direct" ], "description": "How to connect to this pod over SSH. Both variants authenticate with the account's registered SSH public keys (`PUT /v2/account/ssh-keys`), which reach the pod only if it was created with `startSsh` — a pod created without it has no SSH access regardless of what this block reports.", "properties": { "proxy": { "description": "Connection through Runpod's SSH proxy. Works without exposing a port and without a public IP, but carries an interactive shell only — SCP, SFTP, rsync, and port forwarding need `direct`. Null until the pod has a machine assignment.", "anyOf": [ { "$ref": "#/components/schemas/PodSshEndpoint" }, { "type": "null" } ] }, "direct": { "description": "Connection straight to the pod's sshd over its published `22/tcp` mapping. Supports the full SSH feature set. Null unless `22/tcp` is in `ports` and the running pod has been assigned a public port for it — so it is usually absent while the pod is provisioning or stopped. It can still appear on a stopped pod, so check that `status` is `RUNNING` before connecting. Also null when listing pods with `GET /v2/pods`; fetch a single pod by ID to obtain the live mapping.", "anyOf": [ { "$ref": "#/components/schemas/PodSshEndpoint" }, { "type": "null" } ] } } }, "Limit": { "type": "object", "required": [ "limit" ], "properties": { "limit": { "type": [ "integer", "null" ], "description": "The cap. Null when the account has no limit.", "examples": [ 10 ] } } }, "AccountLimits": { "type": "object", "required": [ "spendRate", "serverlessWorkers" ], "properties": { "spendRate": { "type": "object", "required": [ "limit", "current" ], "description": "Spend rate limit: the hourly cap checked when a Pod or serverless worker starts. The start is refused when the hourly cost of running Pods and serverless workers plus the new one's cost would exceed it.", "properties": { "limit": { "type": [ "number", "null" ], "format": "double", "description": "Spend rate limit in USD per hour. Null when the account has no spend rate limit (postpaid accounts).", "examples": [ 80 ] }, "current": { "type": "number", "format": "double", "description": "Current spend rate in USD per hour, the same value the console shows next to the limit. It also counts storage (network volumes, stopped Pods' disks), so it can be slightly higher than what the limit is checked against.", "examples": [ 12.4 ] } } }, "serverlessWorkers": { "$ref": "#/components/schemas/Limit", "description": "Sum of workersMax across all serverless endpoints." } } }, "Account": { "type": "object", "description": "The account the API key belongs to.", "required": [ "id", "email" ], "properties": { "id": { "type": "string", "description": "Account ID. For a request that acts for a team (a key created inside the team, or `X-Team-Id`) this is the team owner's account. For an organization member it is the member's own account; see `GET /v2/organization` for the organization.", "examples": [ "user_2abc123" ] }, "email": { "type": [ "string", "null" ], "description": "Email of the same account. Null when the account has no email on file.", "examples": [ "dev@example.com" ] } } }, "SshKeys": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "string" }, "description": "The account's registered SSH public keys, one authorized_keys-style entry per element (` [comment]`).", "examples": [ [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILXGDN/SclOozk1xsDztpmhGiKkkrfQB9SKoO8dSIQQZ me@example.com" ] ] } } }, "UpdateSshKeysRequest": { "type": "object", "additionalProperties": false, "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "string", "pattern": "^(ssh|ecdsa|sk)-[^\\s]+ [^\\s]+([ \\t][^\\n\\r]*)?$" }, "description": "The full set of SSH public keys to register — this is a complete\nreplacement, not a merge. Each entry is an authorized_keys-style\nline: ` [comment]`, e.g. from\n`~/.ssh/id_ed25519.pub`. Send `[]` to remove all keys. These keys\nare provisioned into pods created with `startSsh` and\nauthenticate both SSH paths reported in the pod's `ssh` block.\n", "examples": [ [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILXGDN/SclOozk1xsDztpmhGiKkkrfQB9SKoO8dSIQQZ me@example.com" ] ] } } }, "CreateAuthenticationAttemptRequest": { "type": "object", "additionalProperties": false, "required": [ "email", "keyName", "codeChallenge" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Address to send the verification code to. It may belong to an existing account or a new one.", "examples": [ "owner@example.com" ] }, "keyName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Name of the API key issued when verification succeeds.", "examples": [ "laptop-cli" ] }, "codeChallenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Unpadded base64url SHA-256 hash of a random `codeVerifier` the caller keeps private. Verify and resend require the matching verifier.", "examples": [ "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM" ] } } }, "VerifyAuthenticationAttemptRequest": { "type": "object", "additionalProperties": false, "required": [ "code", "codeVerifier" ], "properties": { "code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Verification code from the email.", "examples": [ "123456" ] }, "codeVerifier": { "$ref": "#/components/schemas/CodeVerifier" } } }, "ResendAuthenticationAttemptRequest": { "type": "object", "additionalProperties": false, "required": [ "codeVerifier" ], "properties": { "codeVerifier": { "$ref": "#/components/schemas/CodeVerifier" } } }, "CodeVerifier": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{43,128}$", "description": "The random secret whose SHA-256 hash was sent as `codeChallenge`.", "examples": [ "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" ] }, "AuthenticationAttempt": { "type": "object", "required": [ "attemptId", "expiresAt", "resendAfter" ], "properties": { "attemptId": { "type": "string", "description": "Identifies the attempt in verify and resend.", "examples": [ "att_3kq9x81mzp" ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the attempt stops accepting codes. Resending does not extend it.", "examples": [ "2026-10-16T18:10:00Z" ] }, "resendAfter": { "type": "string", "format": "date-time", "description": "Earliest time a resend is accepted.", "examples": [ "2026-10-16T18:00:30Z" ] } } }, "AuthenticationAttemptResult": { "type": "object", "required": [ "userId", "credential" ], "properties": { "userId": { "type": "string", "examples": [ "user_2abc9xyz" ] }, "credential": { "type": "object", "required": [ "id", "apiKey" ], "properties": { "id": { "type": "string", "description": "Identifies the key in the console, where it can be revoked.", "examples": [ "key_7Rk2m0pq" ] }, "apiKey": { "type": "string", "description": "The raw API key. It is returned once, so store it before doing anything else.", "examples": [ "rpa_EXAMPLEONLYEXAMPLEONLYEXAMPLEONLY" ] } } } } }, "Secret": { "type": "object", "description": "An account-scoped secret: an encrypted string stored by Runpod, referenced from pod, serverless, and template environment variables with the `{{ RUNPOD_SECRET_ }}` placeholder, substituted with the secret's value when the pod or worker boots. The value is write-only and never returned by the API.", "required": [ "id", "name", "createdAt" ], "properties": { "id": { "type": "string", "description": "Unique secret identifier", "examples": [ "2q9m7x4cavgd" ] }, "name": { "type": "string", "description": "Unique, human-readable name — the `` referenced by the `RUNPOD_SECRET_` placeholder. Immutable after creation.", "examples": [ "hf-token" ] }, "description": { "type": [ "string", "null" ], "description": "Human-readable description", "examples": [ "Hugging Face read token" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the secret was created" }, "valueLastUpdatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the secret's value was last set (creation or rotation)" } } }, "CreateSecretRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 191, "pattern": "^[a-zA-Z_][a-zA-Z0-9_.\\-/]*$", "description": "Unique name for the secret — referenced from environment variables as `{{ RUNPOD_SECRET_ }}`; immutable after creation. Maximum 191 characters, must start with a letter or underscore, and may contain letters, digits, and `_.-/`. Names beginning with the reserved prefix `RUNPOD` are rejected (case-insensitive).", "examples": [ "hf-token" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 16777216, "description": "The secret value. Write-only — never returned by the API. Must be smaller than 16 MiB of UTF-8 text (strictly under 16,777,216 bytes)." }, "description": { "type": "string", "maxLength": 65535, "description": "Optional human-readable description, at most 65,535 bytes of UTF-8 text.", "examples": [ "Hugging Face read token" ] } } }, "UpdateSecretRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Only the provided fields are updated; at least one field is required.\nThe secret's `name` is immutable.\n", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 16777216, "description": "New secret value, replacing the current one. Write-only. Must be smaller than 16 MiB of UTF-8 text (strictly under 16,777,216 bytes)." }, "description": { "type": "string", "maxLength": 65535, "description": "New human-readable description, at most 65,535 bytes of UTF-8 text. Send `\"\"` to clear." } } }, "ListSecretsResponse": { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/Secret" } } } }, "Pod": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "type": "object", "required": [ "id", "name", "status", "actions", "image", "args", "disk", "mounts", "ports", "env", "registry", "cloud", "dataCenterId", "cudaVersion", "ssh", "template", "cost", "locked", "runtime", "createdAt", "startedAt", "globalNetworking" ], "properties": { "costCenter": { "$ref": "#/components/schemas/ResourceCostCenter" }, "tags": { "$ref": "#/components/schemas/ResourceTags" }, "id": { "type": "string", "examples": [ "pod_abc123" ] }, "name": { "type": "string", "examples": [ "my-training-pod" ] }, "status": { "$ref": "#/components/schemas/PodStatus" }, "actions": { "type": "array", "description": "Valid state transitions for the current status.", "items": { "$ref": "#/components/schemas/PodAction" } }, "mounts": { "$ref": "#/components/schemas/Mounts" }, "gpu": { "description": "Present for GPU pods; omitted from CPU pods.", "allOf": [ { "$ref": "#/components/schemas/GpuConfig" } ] }, "cpu": { "description": "Present for CPU pods; omitted from GPU pods.", "allOf": [ { "$ref": "#/components/schemas/CpuConfig" } ] }, "cloud": { "$ref": "#/components/schemas/Cloud" }, "dataCenterId": { "type": [ "string", "null" ], "description": "Data center where the pod is running (assigned by scheduler)", "examples": [ "US-TX-3" ] }, "cudaVersion": { "type": [ "string", "null" ], "description": "CUDA version reported by the host machine. Retained while the pod is stopped — a stopped pod keeps its machine assignment and resumes onto the same host. Null means unknown or not applicable (CPU pods, or a host that has not reported one), not that CUDA is absent.", "examples": [ "12.8" ] }, "ssh": { "allOf": [ { "$ref": "#/components/schemas/PodSsh" } ], "description": "SSH connection details, via the Runpod proxy or directly to the pod's published `22/tcp` port." }, "cluster": { "description": "Cluster membership; omitted from a standalone pod. Member pods are managed through `/v2/clusters/{id}` — they are excluded from `GET /v2/pods` by default (pass `includeClusterPods=true` to include them) and cannot be modified or deleted via the pod endpoints.", "allOf": [ { "$ref": "#/components/schemas/PodCluster" } ] }, "template": { "type": [ "string", "null" ], "description": "ID of the template this pod was created from", "examples": [ null ] }, "cost": { "type": "number", "format": "float", "description": "The pod's hourly compute rate in USD. It's returned in every status, including `EXITED`, so it isn't what you're paying right now: a stopped pod isn't billed for compute, only for its volume disk.", "examples": [ 0.35 ] }, "locked": { "type": "boolean", "description": "Whether the pod is locked (prevents stopping or resetting)", "examples": [ false ] }, "globalNetworking": { "$ref": "#/components/schemas/PodGlobalNetworking" }, "runtime": { "description": "Live utilization metrics. Null when the pod is not RUNNING, and when listing pods with `GET /v2/pods`; fetch a single pod by ID to obtain metrics.", "anyOf": [ { "$ref": "#/components/schemas/PodRuntime" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "examples": [ "2026-03-13T20:00:00Z" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-03-13T20:00:00Z" ] } } } ] }, "CreatePodRequest": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "type": "object", "required": [ "name" ], "description": "Request body for creating a pod. Exactly one of `gpu` or `cpu`\nmust be set — enforced at the handler layer. For CPU pods, memory\nis derived by the API from the selected flavor's RAM multiplier;\nclients provide only CPU flavor and vCPU count. CPU pods support\ncontainer disk, network volumes, and a global volume;\n`mounts.persistent` is invalid when `cpu` is set.\n\n`image` is required unless `templateId` is set.\n", "properties": { "name": { "type": "string", "minLength": 1, "examples": [ "my-training-pod" ] }, "cloud": { "allOf": [ { "$ref": "#/components/schemas/Cloud" } ], "default": "SECURE", "description": "Cloud tier. Defaults to `SECURE` when omitted." }, "cpu": { "$ref": "#/components/schemas/CreateCpuConfig" }, "dataCenterIds": { "type": "array", "items": { "type": "string" }, "description": "Preferred data centers for placement. Omit or pass an empty\narray to let the scheduler choose.\n", "examples": [ [ "US-TX-3" ] ] }, "globalNetworking": { "type": "boolean", "default": false, "description": "Enable global networking, giving the pod a private IP reachable across data centers. Requires an NVIDIA GPU and a global-networking-enabled data center. See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers.", "examples": [ false ] }, "gpu": { "$ref": "#/components/schemas/CreateGpuConfig" }, "mounts": { "$ref": "#/components/schemas/Mounts" }, "startJupyter": { "type": "boolean", "default": false, "description": "Create-time flag telling the provisioner to start JupyterLab:\ninjects a generated `JUPYTER_PASSWORD` environment variable,\nunless the request already sets one. Only images that honor\nthe convention start Jupyter from it (Runpod official images\ndo); expose `8888/http` in `ports` to reach it.\n\nNot part of the pod's readable config — never returned by\nGET and not changeable by PATCH.\n", "examples": [ true ] }, "startSsh": { "type": "boolean", "default": false, "description": "Create-time flag telling the provisioner to set up SSH\naccess: injects a `PUBLIC_KEY` environment variable carrying\nyour account's registered SSH public keys, unless the request\nalready sets one. **Requires registered keys** (`PUT\n/v2/account/ssh-keys`); with none registered the flag does\nnothing and the pod has no SSH access. Only images that honor\nthe convention start sshd from it (all Runpod official images\ndo). Connect using the pod's `ssh` block; the `ssh.direct`\nvariant additionally needs a `22/tcp` entry in `ports`.\n\nNot part of the pod's readable config — never returned by\nGET and not changeable by PATCH.\n", "examples": [ true ] }, "templateId": { "type": "string", "minLength": 1, "description": "ID of a pod template to base this pod on. The template is\nresolved at create time into the same container settings you\ncould otherwise spread into this body (image, args, disk,\nports, env, registry, persistent mount, startSsh,\nstartJupyter, allowedCudaVersions); explicit body fields\noverride the template's, except `env`, which is merged per\nkey with body values winning. Sending either CUDA field\n(`gpu.allowedCudaVersions` or `gpu.minCudaVersion`) replaces\nthe template's CUDA constraint entirely, and CPU pods ignore\nit (like the persistent mount). The template is a one-time\nsource of settings: later template edits do not affect the\npod, and the created pod does not retain a link to the\ntemplate (`template` stays null). The template may be one\nof your own or a public catalog template — see\n`GET /v2/catalog/templates` (unknown or inaccessible ID →\n404) — and must not be a serverless template (→ 422). CPU\npods do not inherit a template's persistent mount.\n", "examples": [ "30zmvf89kd" ] }, "queue": { "$ref": "#/components/schemas/PodQueueOptions" } } } ], "unevaluatedProperties": false, "if": { "not": { "required": [ "templateId" ] } }, "then": { "required": [ "image" ] } }, "UpdatePodRequest": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "type": "object", "properties": { "globalNetworking": { "type": "boolean", "description": "Enable (true) or disable (false) global networking. Takes effect on the next pod start/restart, not live. Requires an NVIDIA GPU and a global-networking-enabled data center. See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers." }, "locked": { "type": "boolean", "description": "Lock the pod (true) or unlock it (false). Locked pods cannot be stopped or reset." }, "mounts": { "$ref": "#/components/schemas/UpdatePodMounts" }, "name": { "type": "string", "minLength": 1 }, "templateId": { "type": "string", "description": "ID of a pod template whose container settings are applied as\nif they were provided in this PATCH body (image, args, disk,\nports, env, registry — mounts are not applied on update).\nExplicit body fields override the template's; `env` merges\ntemplate and body per key (body wins) and, per PATCH\nsemantics, replaces the pod's env. One-time application —\nno link to the template is retained. Must be one of your\ntemplates or a public template (unknown or inaccessible ID\n→ 404); must not be a serverless template (→ 422).\n", "examples": [ "30zmvf89kd" ] } } } ], "unevaluatedProperties": false }, "PodActionRequest": { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/PodAction" } } }, "PodExecRequest": { "type": "object", "additionalProperties": false, "required": [ "command" ], "properties": { "command": { "type": "array", "minItems": 1, "maxItems": 256, "prefixItems": [ { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^[^\\x00]*[^\\t-\\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\\x00][^\\x00]*$" } ], "items": { "type": "string", "maxLength": 4096, "pattern": "^[^\\x00]*$" }, "description": "Command to run, as an argv array of 1-256 arguments of at most 4096\ncharacters each. It is run directly, never through a shell; for\npipes, redirects or globbing pass `[\"sh\", \"-c\", \"...\"]`. The first\nelement, the program, must contain a non-whitespace character;\nlater arguments may be empty. No argument may contain a NUL\ncharacter.\n", "examples": [ [ "nvidia-smi", "--query-gpu=name,memory.used", "--format=csv" ] ] }, "timeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 25, "default": 20, "description": "How long the call waits for the command to finish, in seconds. A\ncommand still running at this point returns with `timedOut: true`.\n", "examples": [ 10 ] }, "cwd": { "type": "string", "pattern": "^/[^\\x00-\\x1f\\x7f]*$", "maxLength": 1024, "description": "Absolute working directory for the command, at most 1024 characters\nand without control characters. Defaults to the image's `WORKDIR`.\n", "examples": [ "/workspace" ] }, "env": { "type": "object", "maxProperties": 64, "propertyNames": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^=\\x00]+$" }, "additionalProperties": { "type": "string", "maxLength": 16384, "pattern": "^[^\\x00]*$" }, "description": "Up to 64 environment variables added to the container's environment\nfor this command only. A name is 1-256 characters and must not\ncontain `=` or a NUL character; a value is at most 16384 characters\nand must not contain a NUL character.\n", "examples": [ { "HF_HOME": "/workspace/hf" } ] } } }, "PodExecResult": { "type": "object", "required": [ "stdout", "stderr", "exitCode", "timedOut", "truncated", "durationMs" ], "properties": { "stdout": { "type": "string", "description": "The command's standard output, as UTF-8 with invalid bytes\nreplaced. Capped at 1 MiB; see `truncated`.\n" }, "stderr": { "type": "string", "description": "The command's standard error, as UTF-8 with invalid bytes\nreplaced. Capped at 1 MiB; see `truncated`.\n" }, "exitCode": { "type": [ "integer", "null" ], "description": "The command's exit code. A non-zero code is a result, not an error.\nNull only when `timedOut` is `true`.\n" }, "timedOut": { "type": "boolean", "description": "The call stopped waiting at `timeoutSeconds`. It does not mean the\ncommand was stopped: it may still be running inside the container.\n" }, "truncated": { "type": "boolean", "description": "`stdout` or `stderr` reached the 1 MiB cap and was cut." }, "durationMs": { "type": "integer", "description": "Wall time of the command as measured on the pod's machine, in milliseconds." } } }, "PodList": { "type": "object", "description": "A bare list of pods. `GET /v2/clusters/{id}/pods` returns it as-is (a cluster's members are a small, complete set); `GET /v2/pods` composes it with the pagination block via ListPodsResponse.\n", "required": [ "pods" ], "properties": { "pods": { "type": "array", "items": { "$ref": "#/components/schemas/Pod" } } } }, "ListPodsResponse": { "allOf": [ { "$ref": "#/components/schemas/PodList" }, { "$ref": "#/components/schemas/Paginated" } ] }, "PodQueueAllowedHours": { "type": "object", "description": "Hours of the day, in UTC, during which the queued pod may deploy, per\nweekday. Omit the object to allow any time. A weekday that is omitted\nis unrestricted; an empty array blocks that whole day. Each entry is\nan hour from 0 to 23 and allows deploys from that hour to the next.\n", "properties": { "monday": { "$ref": "#/components/schemas/PodQueueHours" }, "tuesday": { "$ref": "#/components/schemas/PodQueueHours" }, "wednesday": { "$ref": "#/components/schemas/PodQueueHours" }, "thursday": { "$ref": "#/components/schemas/PodQueueHours" }, "friday": { "$ref": "#/components/schemas/PodQueueHours" }, "saturday": { "$ref": "#/components/schemas/PodQueueHours" }, "sunday": { "$ref": "#/components/schemas/PodQueueHours" } }, "unevaluatedProperties": false }, "PodQueueHours": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 23 }, "examples": [ [ 9, 10, 11, 12, 13, 14, 15, 16 ] ] }, "QueuedPodSchedule": { "type": "object", "description": "The `queue` options as stored, with the defaults applied.", "required": [ "startsAt", "expiresAt", "allowedHours", "notifyEmail" ], "properties": { "startsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When waiting begins. Null when it began with the request.", "examples": [ null ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "When waiting ends.", "examples": [ "2026-07-01T12:00:00Z" ] }, "allowedHours": { "anyOf": [ { "$ref": "#/components/schemas/PodQueueAllowedHours" }, { "type": "null" } ], "description": "Null when any hour is allowed." }, "notifyEmail": { "type": [ "string", "null" ], "format": "email", "description": "Null when no email was asked for.", "examples": [ null ] } } }, "QueuedPodStatus": { "type": "string", "description": "Where a queued pod is in its life.\n- `QUEUED` — waiting for capacity (from `queue.startsAt` when set)\n- `DEPLOYED` — capacity came and a pod was created; `podId` names it\n- `FAILED` — capacity came but the deploy was refused for good; `failureReason` says why\n- `EXPIRED` — `queue.expiresAt` passed without capacity\n- `CANCELLED` — cancelled with `DELETE /v2/queued-pods/{id}`\n", "x-enum-varnames": [ "QueuedPodStatusQueued", "QueuedPodStatusDeployed", "QueuedPodStatusFailed", "QueuedPodStatusExpired", "QueuedPodStatusCancelled" ], "enum": [ "QUEUED", "DEPLOYED", "FAILED", "EXPIRED", "CANCELLED" ] }, "QueuedPodFailureReason": { "type": "string", "description": "Why a `FAILED` queued pod could not deploy once capacity came.\n- `INSUFFICIENT_BALANCE` — the account balance was too low\n- `SPENDING_LIMIT` — the deploy would have passed the spending limit\n- `GPU_QUOTA_EXCEEDED` — the account's quota for this GPU type was reached\n- `GPU_CONCURRENCY_EXCEEDED` — the plan's concurrent GPU cap was reached\n- `ORG_RESTRICTED` — the account joined an organization, which cannot use queued deploys\n- `UNKNOWN` — anything else; contact support\n", "x-enum-varnames": [ "QueuedPodFailureReasonInsufficientBalance", "QueuedPodFailureReasonSpendingLimit", "QueuedPodFailureReasonGpuQuotaExceeded", "QueuedPodFailureReasonGpuConcurrencyExceeded", "QueuedPodFailureReasonOrgRestricted", "QueuedPodFailureReasonUnknown" ], "enum": [ "INSUFFICIENT_BALANCE", "SPENDING_LIMIT", "GPU_QUOTA_EXCEEDED", "GPU_CONCURRENCY_EXCEEDED", "ORG_RESTRICTED", "UNKNOWN" ] }, "QueuedPod": { "type": "object", "description": "A pod waiting for capacity, or the record of one that waited. It\ncarries what identifies and schedules the request; the full container\nsettings are not echoed back, keep your create request.\n", "required": [ "id", "status", "podId", "failureReason", "name", "image", "templateId", "gpu", "cloud", "dataCenterIds", "queue", "createdAt", "resolvedAt" ], "properties": { "id": { "type": "string", "examples": [ "clz1x9k4a0000qw3h8s7d2f1g" ] }, "status": { "$ref": "#/components/schemas/QueuedPodStatus" }, "podId": { "type": [ "string", "null" ], "description": "The pod created once capacity came; null until then. Read it with `GET /v2/pods/{id}`.", "examples": [ null ] }, "failureReason": { "anyOf": [ { "$ref": "#/components/schemas/QueuedPodFailureReason" }, { "type": "null" } ], "description": "Set only when `status` is `FAILED`." }, "name": { "type": "string", "description": "The name the pod will carry.", "examples": [ "pytorch-training" ] }, "image": { "type": [ "string", "null" ], "description": "The image the pod will run. Null when it comes from `templateId` at deploy time.", "examples": [ "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404" ] }, "templateId": { "type": [ "string", "null" ], "description": "The template the scheduler resolves at deploy time. Null for queued\npods from this API, which expands `templateId` into `image` when\nthe request is made.\n", "examples": [ null ] }, "gpu": { "$ref": "#/components/schemas/BaseGpuConfig" }, "cloud": { "$ref": "#/components/schemas/Cloud" }, "dataCenterIds": { "type": "array", "items": { "type": "string" }, "description": "The data centers the deploy is limited to; empty when any will do.", "examples": [ [ "EU-RO-1" ] ] }, "queue": { "$ref": "#/components/schemas/QueuedPodSchedule" }, "createdAt": { "type": "string", "format": "date-time", "examples": [ "2026-06-01T12:00:00Z" ] }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the queued pod deployed, failed or expired. Null while it waits, and after a cancel.", "examples": [ null ] } } }, "PodQueueOptions": { "type": "object", "description": "Queue the pod for deploy-when-available instead of failing when the\nrequested GPU has no capacity. The create call still tries to deploy\nfirst; only a capacity failure queues the request, and any other\nfailure is returned as it would be without `queue`. A queued pod is\nplaced by a scheduler that retries about every five minutes, in plan\npriority order, during `allowedHours`, until `expiresAt`. An empty\nobject queues with the defaults.\n\nGPU pods on the secure cloud only: `queue` with `cpu` or\n`globalNetworking` is rejected with `400`. A plan without\ndeploy-when-available is refused with `403`, and one whose queue is\nfull with `409`. A request that matches a pod still queued (same GPU\ntype and count, same settings) returns that queued pod rather than a\nsecond one.\n", "properties": { "startsAt": { "type": "string", "format": "date-time", "description": "Begin waiting at this future time instead of now. The create call\nthen does not try to deploy first; the pod is queued at once. A\ntime already past is a `400`.\n", "examples": [ "2026-06-02T08:00:00Z" ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "Stop waiting at this time; the queued pod then reports `EXPIRED`.\nDefaults to, and is capped at, 30 days after `startsAt` (or after\nthe request when `startsAt` is omitted). A time already past, or\none not after `startsAt`, is a `400`.\n", "examples": [ "2026-06-03T08:00:00Z" ] }, "allowedHours": { "$ref": "#/components/schemas/PodQueueAllowedHours" }, "notifyEmail": { "type": "string", "format": "email", "description": "Also email this address when the pod deploys, or when the queued\npod fails or expires. Must be an address on your account (`422`\notherwise).\n", "examples": [ "ops@example.com" ] } }, "unevaluatedProperties": false }, "QueuedPodList": { "type": "object", "required": [ "queuedPods" ], "properties": { "queuedPods": { "type": "array", "items": { "$ref": "#/components/schemas/QueuedPod" } } } }, "ListQueuedPodsResponse": { "allOf": [ { "$ref": "#/components/schemas/QueuedPodList" }, { "$ref": "#/components/schemas/Paginated" } ] }, "ClusterType": { "type": "string", "description": "Cluster type. TRAINING is the generic distributed-training cluster; SLURM provisions a managed Slurm controller/compute topology; RAY provisions a managed Ray head/worker topology; APPLICATION is a general multi-node application cluster.", "enum": [ "APPLICATION", "TRAINING", "SLURM", "RAY" ], "examples": [ "TRAINING" ] }, "ClusterCompute": { "type": "object", "additionalProperties": false, "description": "The homogeneous compute shape of a cluster. Every pod in the cluster is identical: `podCount` pods, each with `gpuCountPerPod` GPUs of type `gpuTypeId`. Total GPUs = `podCount` * `gpuCountPerPod`.", "required": [ "gpuTypeId", "gpuCountPerPod", "podCount" ], "properties": { "gpuTypeId": { "type": "string", "minLength": 1, "description": "GPU type for every pod in the cluster, as returned by GET /v2/catalog/gpus.", "examples": [ "NVIDIA H100 80GB HBM3" ] }, "gpuCountPerPod": { "type": "integer", "minimum": 1, "description": "Number of GPUs on each pod. Bounded above by the GPU type's per-cloud maximum (GpuType.maxCount); values beyond it are rejected.", "examples": [ 8 ] }, "podCount": { "type": "integer", "minimum": 2, "maximum": 250, "description": "Number of pods (nodes) in the cluster.", "examples": [ 4 ] } } }, "PodClusterRole": { "type": "string", "description": "A cluster member's role. Assigned for SLURM and RAY clusters; omitted for TRAINING/APPLICATION members.", "enum": [ "SLURM_CONTROLLER", "SLURM_COMPUTE", "RAY_HEAD", "RAY_WORKER" ] }, "PodCluster": { "type": "object", "additionalProperties": false, "description": "A pod's membership in a cluster.", "required": [ "id", "rank" ], "properties": { "id": { "type": "string", "description": "ID of the cluster this pod belongs to.", "examples": [ "cluster_abc123" ] }, "rank": { "type": [ "integer", "null" ], "description": "The pod's node rank within the cluster (NODE_RANK), or null until the index is assigned during provisioning. Rank 0 is the cluster's entry node (`Cluster.primary`); for SLURM it is the controller.", "examples": [ 0 ] }, "role": { "description": "SLURM or RAY role; omitted for TRAINING/APPLICATION clusters, which do not assign roles.", "allOf": [ { "$ref": "#/components/schemas/PodClusterRole" } ] }, "ip": { "type": "string", "description": "The pod's address on the cluster's private overlay network; omitted until the address is assigned.", "examples": [ "10.65.0.2" ] } } }, "ClusterNetwork": { "type": "object", "additionalProperties": false, "description": "The cluster's private VXLAN overlay network (shared by all member pods).", "required": [ "cidr" ], "properties": { "cidr": { "type": "string", "description": "The overlay network's CIDR block.", "examples": [ "10.65.0.0/16" ] }, "vxlanId": { "type": "integer", "description": "VXLAN network identifier; omitted until assigned.", "examples": [ 42 ] }, "vxlanPort": { "type": "integer", "description": "UDP port carrying the VXLAN traffic; omitted until assigned.", "examples": [ 4789 ] } } }, "ClusterPrimary": { "type": "object", "additionalProperties": false, "description": "The cluster's primary (master) node, through which the cluster is typically driven. Omitted until a primary pod has been placed.", "required": [ "podId", "status" ], "properties": { "podId": { "type": "string", "description": "ID of the primary member pod.", "examples": [ "pod_node0" ] }, "status": { "$ref": "#/components/schemas/PodStatus" }, "sshEndpoint": { "type": "string", "description": "Public SSH endpoint (`host:port`) for the primary node; omitted when the primary is not yet RUNNING or does not expose SSH (22/tcp).", "examples": [ "1.2.3.4:22001" ] } } }, "ClusterPodsSummary": { "type": "object", "additionalProperties": false, "description": "A lightweight summary of a cluster's member pods. Use `GET /v2/clusters/{id}/pods` to retrieve the full pod objects.", "required": [ "total", "byStatus" ], "properties": { "total": { "type": "integer", "description": "Number of member pods currently provisioned for the cluster.", "examples": [ 4 ] }, "byStatus": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Member pod counts keyed by pod status (the same values as `Pod.status`, e.g. RUNNING, PROVISIONING). Statuses with no pods are omitted.", "example": { "RUNNING": 3, "PROVISIONING": 1 } } } }, "Cluster": { "type": "object", "description": "A cluster. Cluster-level fields describe the identity and homogeneous shape; `pods` is a lightweight summary of the members. Fetch the full member pods — with their container config, mounts, and runtime state — from `GET /v2/clusters/{id}/pods`.", "required": [ "id", "name", "type", "compute", "pods", "createdAt" ], "properties": { "costCenter": { "$ref": "#/components/schemas/ResourceCostCenter" }, "tags": { "$ref": "#/components/schemas/ResourceTags" }, "id": { "type": "string", "examples": [ "cluster_abc123" ] }, "name": { "type": "string", "examples": [ "my-training-cluster" ] }, "type": { "$ref": "#/components/schemas/ClusterType" }, "compute": { "$ref": "#/components/schemas/ClusterCompute" }, "template": { "type": "string", "description": "ID of the template this cluster's pods were created from; omitted when they were not created from one.", "examples": [ "tpl_abc" ] }, "dataCenterId": { "type": "string", "description": "Data center the cluster is placed in (a cluster is always within a single data center). Derived from the member pods; omitted until at least one pod is placed.", "examples": [ "US-TX-3" ] }, "pods": { "$ref": "#/components/schemas/ClusterPodsSummary" }, "network": { "description": "The cluster's overlay network; omitted until the network is provisioned.", "allOf": [ { "$ref": "#/components/schemas/ClusterNetwork" } ] }, "primary": { "description": "The primary (master) node; omitted until a primary pod is placed. Its `sshEndpoint` is omitted until that pod is RUNNING with SSH exposed.", "allOf": [ { "$ref": "#/components/schemas/ClusterPrimary" } ] }, "createdAt": { "type": "string", "format": "date-time", "examples": [ "2026-06-29T20:00:00Z" ] } } }, "CreateClusterRequest": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "type": "object", "required": [ "name", "type", "compute" ], "description": "Request body for creating a cluster. `compute` defines the\nhomogeneous pod shape; the container configuration (image, env, ports,\nregistry, …) applies to every pod. Pass `templateId` to provision\nevery member pod from a pod template instead of inline container\nfields. For a private image, pass `registry` (one of your\ncredentials from `/v2/registries`); it is attached to every member\npod, and an ID that does not exist or is not yours is a 400.\n", "properties": { "compute": { "$ref": "#/components/schemas/ClusterCompute" }, "name": { "type": "string", "minLength": 1, "examples": [ "my-training-cluster" ] }, "type": { "$ref": "#/components/schemas/ClusterType" }, "templateId": { "type": "string", "minLength": 1, "description": "ID of a pod template to provision every member pod from. The\ntemplate supplies the container settings (image, args, disk,\nenv, ports) and the container registry credential for private\nimages. Mutually exclusive with `image`, `args`, `entrypoint`,\n`cmd`, `disk`, `env`, and `ports` (rejected with 400). `registry`\ncombines with it: an explicit `registry` overrides the\ntemplate's credential; omit it (or send `null` or an empty\nstring) to use the template's. `mounts`\ncombines with it too: the volume in `mounts` is attached to\nevery member pod, overriding the template's volume settings. The cluster\nretains the link: the `template` response field is set. Must be\na non-serverless pod template accessible to the caller.\n", "examples": [ "30zmvf89kd" ] }, "dataCenterIds": { "type": "array", "items": { "type": "string" }, "description": "Preferred data centers for placement. Omit or pass an empty\narray to let the scheduler choose. A cluster is always placed\nwithin a single data center.\n", "example": [ "US-TX-3" ] }, "mounts": { "$ref": "#/components/schemas/ClusterMounts" }, "startJupyter": { "type": "boolean", "default": false, "description": "Start Jupyter on every member pod, as on pod create." }, "startSsh": { "type": "boolean", "default": false, "description": "Provision SSH access on every member pod: injects a PUBLIC_KEY environment variable carrying your account's registered SSH public key. Same semantics as the pod create flag." } } } ], "unevaluatedProperties": false }, "UpdateClusterRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Request body for updating a cluster. Only the cluster name can be\nchanged — this endpoint is a rename. Compute shape, type, and container\nconfiguration are fixed at creation.\n", "properties": { "name": { "type": "string", "minLength": 1, "examples": [ "renamed-cluster" ] } } }, "ListClustersResponse": { "type": "object", "required": [ "clusters", "pagination" ], "properties": { "clusters": { "type": "array", "items": { "$ref": "#/components/schemas/Cluster" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Template": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "type": "object", "required": [ "id", "name", "image", "args", "disk", "mounts", "ports", "env", "registry", "serverless", "public", "category", "startSsh", "startJupyter", "allowedCudaVersions" ], "properties": { "id": { "type": "string", "examples": [ "tpl_abc" ] }, "name": { "type": "string", "examples": [ "My PyTorch Template" ] }, "mounts": { "$ref": "#/components/schemas/TemplateMounts" }, "serverless": { "type": "boolean", "description": "Whether this template is for serverless workers (true) or pods (false)", "examples": [ false ] }, "public": { "type": "boolean", "description": "Whether this template is visible to other Runpod users", "examples": [ false ] }, "category": { "$ref": "#/components/schemas/TemplateCategory" }, "startSsh": { "type": "boolean", "description": "Whether containers created from this template get SSH access provisioned at startup (`PUBLIC_KEY` env injection).", "examples": [ true ] }, "startJupyter": { "type": "boolean", "description": "Whether containers created from this template start JupyterLab at startup (`JUPYTER_PASSWORD` env injection).", "examples": [ false ] }, "allowedCudaVersions": { "type": "array", "items": { "type": "string" }, "description": "Acceptable CUDA versions for containers created from this template, as `major.minor`. Empty means any version. Expanded into GPU pod and serverless endpoint creates; CPU pods ignore it.", "examples": [ [] ] } } } ] }, "CreateTemplateRequest": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "type": "object", "required": [ "name", "image" ], "properties": { "name": { "type": "string", "minLength": 1, "examples": [ "My PyTorch Template" ] }, "allowedCudaVersions": { "type": "array", "items": { "type": "string", "pattern": "^\\d+\\.\\d+$" }, "description": "Acceptable CUDA versions for containers created from this\ntemplate, as `major.minor`. Omit to accept any version — see\nthe same field on `createPod` for matching semantics.\nExpanded into GPU pod and serverless endpoint creates; CPU\npods ignore it.\n", "examples": [ [ "12.8", "12.6" ] ] }, "category": { "description": "Optional. Defaults to `NVIDIA` when omitted.", "allOf": [ { "$ref": "#/components/schemas/TemplateCategory" } ], "default": "NVIDIA" }, "mounts": { "$ref": "#/components/schemas/TemplateMounts" }, "public": { "type": "boolean", "default": false }, "serverless": { "type": "boolean", "default": false }, "startJupyter": { "type": "boolean", "default": true, "description": "Start JupyterLab in containers created from this template:\ninjects a generated `JUPYTER_PASSWORD` environment variable,\nunless `env` already sets one. Only images that honor the\nconvention start Jupyter from it (Runpod official images do);\nexpose `8888/http` in `ports` to reach it. Defaults to `true`\nwhen omitted, matching console-created templates.\n", "examples": [ false ] }, "startSsh": { "type": "boolean", "default": true, "description": "Provision SSH access in containers created from this template:\ninjects a `PUBLIC_KEY` environment variable carrying the\ndeployer's registered SSH public keys (`PUT\n/v2/account/ssh-keys` — with none registered the flag does\nnothing), unless `env` already sets one. Only images that\nhonor the convention start sshd from it (all Runpod official\nimages do); direct SSH also needs a `22/tcp` entry in\n`ports`. Defaults to `true` when omitted, matching\nconsole-created templates.\n", "examples": [ true ] } } } ], "unevaluatedProperties": false }, "UpdateTemplateRequest": { "allOf": [ { "$ref": "#/components/schemas/ContainerConfig" }, { "type": "object", "properties": { "allowedCudaVersions": { "type": "array", "items": { "type": "string", "pattern": "^\\d+\\.\\d+$" }, "description": "Acceptable CUDA versions for pods created from this template. An explicit `[]` clears the constraint; omitting the field leaves it unchanged." }, "category": { "$ref": "#/components/schemas/TemplateCategory" }, "mounts": { "$ref": "#/components/schemas/TemplateMounts" }, "name": { "type": "string", "minLength": 1 }, "public": { "type": "boolean" }, "serverless": { "type": "boolean" }, "startJupyter": { "type": "boolean", "description": "Start JupyterLab at container startup (`JUPYTER_PASSWORD` env injection). See the create-time field for details." }, "startSsh": { "type": "boolean", "description": "Provision SSH access at container startup (`PUBLIC_KEY` env injection). See the create-time field for details." } } } ], "unevaluatedProperties": false }, "TemplateList": { "type": "object", "description": "A bare list of templates. `GET /v2/catalog/templates` returns it as-is (the catalog is a capped, curated set); `GET /v2/templates` composes it with the pagination block via ListTemplatesResponse.\n", "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } }, "ListTemplatesResponse": { "allOf": [ { "$ref": "#/components/schemas/TemplateList" }, { "$ref": "#/components/schemas/Paginated" } ] }, "NetworkVolume": { "type": "object", "required": [ "id", "name", "size", "dataCenter", "type" ], "properties": { "costCenter": { "$ref": "#/components/schemas/ResourceCostCenter" }, "tags": { "$ref": "#/components/schemas/ResourceTags" }, "id": { "type": "string", "description": "Unique network volume identifier", "examples": [ "agv6w2qcg7" ] }, "name": { "type": "string", "description": "Human-readable name (not required to be unique)", "examples": [ "my-dataset" ] }, "size": { "type": "integer", "minimum": 10, "maximum": 4096, "description": "Allocated storage in GB", "examples": [ 50 ] }, "dataCenter": { "type": "string", "description": "Data center location; immutable after creation", "examples": [ "EU-RO-1" ] }, "type": { "allOf": [ { "$ref": "#/components/schemas/VolumeType" } ], "description": "Storage tier of this volume. Set at creation and immutable." } } }, "CreateNetworkVolumeRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "size", "dataCenter" ], "properties": { "dataCenter": { "type": "string", "minLength": 1, "description": "Data center in which to create the volume", "examples": [ "EU-RO-1" ] }, "name": { "type": "string", "minLength": 1, "description": "Human-readable name", "examples": [ "my-dataset" ] }, "size": { "type": "integer", "minimum": 10, "maximum": 4096, "description": "Storage to allocate in GB", "examples": [ 50 ] }, "type": { "allOf": [ { "$ref": "#/components/schemas/VolumeType" } ], "description": "Storage tier for the volume. Optional. When omitted, the volume is\nprovisioned using the requested data center's default (primary)\nstorage tier. HIGH_PERFORMANCE provisions a high-performance (HPS)\nvolume; STANDARD provisions a standard volume. A volume's tier is\nimmutable after creation.\n" } } }, "UpdateNetworkVolumeRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Only the provided fields are updated. At least one field must be\npresent; an empty body is rejected.\n", "properties": { "name": { "type": "string", "minLength": 1, "description": "New human-readable name", "examples": [ "renamed-volume" ] }, "size": { "type": "integer", "minimum": 10, "maximum": 4096, "description": "New size in GB. Must be greater than or equal to the current size —\nnetwork volume storage cannot be reduced.\n", "examples": [ 100 ] } } }, "ListNetworkVolumesResponse": { "type": "object", "required": [ "networkVolumes", "pagination" ], "properties": { "networkVolumes": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkVolume" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "GlobalVolume": { "type": "object", "required": [ "id", "name", "createdAt", "createdByUserId" ], "properties": { "id": { "type": "string", "description": "Unique global volume identifier", "examples": [ "gsb_abc" ] }, "name": { "type": "string", "description": "Human-readable name (not required to be unique)", "examples": [ "training-data" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the volume was created" }, "createdByUserId": { "type": [ "string", "null" ], "description": "ID of the user who created the volume, if known", "examples": [ "user_123" ] } } }, "CreateGlobalVolumeRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 191, "pattern": "[^\\t-\\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]", "description": "Human-readable name, 1–191 characters with at least one non-whitespace character. Leading and trailing whitespace is trimmed.\n", "examples": [ "training-data" ] } } }, "UpdateGlobalVolumeRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Only the provided fields are updated. At least one field must be\npresent; an empty body is rejected.\n", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 191, "pattern": "[^\\t-\\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]", "description": "New human-readable name, 1–191 characters with at least one non-whitespace character. Leading and trailing whitespace is trimmed.\n", "examples": [ "renamed-volume" ] } } }, "ListGlobalVolumesResponse": { "type": "object", "required": [ "globalVolumes", "pagination" ], "properties": { "globalVolumes": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalVolume" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "EndpointMount": { "type": "object", "required": [ "volumeId" ], "additionalProperties": false, "description": "A volume mounted on every worker, always at `/runpod-volume`. Custom\npaths are not supported yet.\n", "properties": { "volumeId": { "type": "string", "description": "ID of a NetworkVolume (under `network`) or GlobalVolume (under `global`).", "examples": [ "vol_abc" ] } } }, "EndpointMounts": { "type": "object", "required": [ "network", "global" ], "description": "Volumes mounted on every worker of the endpoint.", "properties": { "network": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointMount" } }, "global": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointMount" } } } }, "EndpointMountsInput": { "type": "object", "additionalProperties": false, "description": "Volumes to mount on the endpoint's workers. A `network` or `global`\nlist that is present replaces the endpoint's current list of that kind;\nan empty list detaches it, and an omitted list is left unchanged. Both\nkinds cannot be present on the endpoint at once, so to switch kinds send\n`[]` for one and the new list for the other in the same request. Changes\napply to workers created afterwards. At most one global volume. `network`\nmay accompany the deprecated `networkVolumes` field only if the two agree\nexactly.\n", "properties": { "network": { "type": "array", "description": "Network volumes, at most one per data center.", "items": { "$ref": "#/components/schemas/EndpointMount" } }, "global": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/EndpointMount" } } } }, "Registry": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "examples": [ "reg_abc" ] }, "name": { "type": "string", "examples": [ "my-private-registry" ] } } }, "CreateRegistryRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "username", "password" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 191, "examples": [ "my-private-registry" ] }, "password": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "Registry password (write-only, not returned in responses)" }, "username": { "type": "string", "minLength": 1, "maxLength": 191, "description": "Registry username (write-only, not returned in responses)" } } }, "UpdateRegistryRequest": { "type": "object", "additionalProperties": false, "required": [ "username", "password" ], "properties": { "password": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "New registry password (write-only, not returned in responses)" }, "username": { "type": "string", "minLength": 1, "maxLength": 191, "description": "Registry username to store with the new password (write-only, not returned in responses)" } } }, "ListRegistriesResponse": { "type": "object", "required": [ "registries" ], "properties": { "registries": { "type": "array", "items": { "$ref": "#/components/schemas/Registry" } } } }, "EcrDelegation": { "type": "object", "required": [ "id", "delegatorUserId", "awsUser", "repository", "tag", "awsRegion", "createdAt" ], "properties": { "id": { "type": "string", "description": "Delegation identifier", "examples": [ "deleg_abc123" ] }, "name": { "type": [ "string", "null" ], "description": "Optional name for the delegation", "examples": [ "my-delegation" ] }, "delegatorUserId": { "type": "string", "description": "User ID that created the delegation", "examples": [ "user_xyz" ] }, "awsUser": { "type": "string", "description": "AWS user/role being delegated", "examples": [ "123456789" ] }, "repository": { "type": "string", "description": "ECR repository name", "examples": [ "runpod/deployment" ] }, "tag": { "type": "string", "description": "ECR image tag", "examples": [ "latest" ] }, "awsRegion": { "type": "string", "description": "AWS region", "examples": [ "us-east-2" ] }, "dockerRegistryUri": { "type": "string", "description": "Formatted ECR registry URI for Docker login", "examples": [ "123456789.dkr.ecr.us-east-2.amazonaws.com" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the delegation was created", "examples": [ "2026-03-13T20:00:00Z" ] } } }, "CreateDelegationRequest": { "type": "object", "additionalProperties": false, "required": [ "resource" ], "properties": { "resource": { "type": "string", "description": "ECR resource ARN", "examples": [ "arn:aws:ecr:us-east-2:418399314813:repository/runpod/deployment" ] }, "name": { "type": [ "string", "null" ], "description": "Optional name for the delegation", "examples": [ "my-delegation" ] } } }, "ListDelegationsResponse": { "type": "object", "required": [ "delegations" ], "properties": { "delegations": { "type": "array", "items": { "$ref": "#/components/schemas/EcrDelegation" } } } }, "GpuManufacturer": { "type": "string", "description": "Canonical GPU hardware manufacturer.", "x-enum-varnames": [ "GpuManufacturerNVIDIA", "GpuManufacturerAMD", "GpuManufacturerUNKNOWN" ], "enum": [ "NVIDIA", "AMD", "UNKNOWN" ] }, "GpuType": { "type": "object", "required": [ "id", "name", "pool", "manufacturer", "memory", "secure", "community", "price", "maxCount" ], "properties": { "id": { "type": "string", "description": "Individual GPU type identifier (use for pod creation)", "examples": [ "NVIDIA GeForce RTX 4090" ] }, "name": { "type": "string", "examples": [ "RTX 4090" ] }, "pool": { "type": [ "string", "null" ], "description": "Serverless GPU pool ID (use for serverless endpoint creation). Null if GPU is not in a serverless pool.", "examples": [ "ADA_24" ] }, "manufacturer": { "$ref": "#/components/schemas/GpuManufacturer" }, "memory": { "type": "integer", "description": "VRAM in GB", "examples": [ 24 ] }, "secure": { "type": "boolean", "description": "Available on secure cloud", "examples": [ true ] }, "community": { "type": "boolean", "description": "Available on community cloud", "examples": [ true ] }, "price": { "type": "object", "description": "List price in USD per hour for a **single** GPU of this type. Pod\nrates are quoted separately per cloud (`secure`, `community`);\n`serverless` is the rate for this GPU's pool. In every case the\nrate for a unit is the figure times `gpu.count`; the rate actually\nbilled for a pod is reported as `cost` on the pod itself.\n", "required": [ "secure", "community" ], "properties": { "secure": { "type": "number", "format": "float", "examples": [ 0.44 ] }, "community": { "type": "number", "format": "float", "examples": [ 0.31 ] }, "serverless": { "type": "number", "format": "float", "description": "Serverless list price per GPU per hour, from the `pool` this GPU\nbelongs to. Multiply by `gpu.count` for the per-worker rate.\nAbsent when the GPU is not in a serverless pool available to the\ncaller. Negotiated account discounts are not reflected.\n", "examples": [ 1.1 ] } } }, "maxCount": { "type": "object", "description": "The largest number of GPUs you can request on a single pod of this\ntype, quoted separately per cloud. A pod runs on one machine, so\nthis is the GPU count of the largest machine of this type Runpod\noperates in that cloud.\n\nThis is a ceiling, not a stock level — it does not mean that many\nGPUs are free right now. For current availability, request\n`include=AVAILABILITY&product=POD` and read `availability`\n(overall) or `dataCenters` (per data center).\n", "required": [ "secure", "community" ], "properties": { "secure": { "type": "integer", "examples": [ 8 ] }, "community": { "type": "integer", "examples": [ 4 ] } } }, "minVcpuCount": { "type": "integer", "description": "Minimum total vCPU count reported across matching machines for the\nrequested `count` and availability filters. Present only with\ninclude=AVAILABILITY and omitted when `availability` is `NONE`.\n", "examples": [ 8 ] }, "minRam": { "type": "integer", "description": "Minimum total system RAM in GB reported across matching machines\nfor the requested `count` and availability filters. This is host\nRAM, not the GPU VRAM reported in `memory`. Present only with\ninclude=AVAILABILITY and omitted when `availability` is `NONE`.\n", "examples": [ 32 ] }, "availability": { "description": "Overall GPU availability for the requested `product` contexts. Present only when requested with include=AVAILABILITY, which also requires `product`.", "$ref": "#/components/schemas/AvailabilityLevel" }, "dataCenters": { "type": "array", "description": "Per-datacenter GPU availability for the requested `product`\ncontexts, listing only the datacenters that offer this GPU in the\nrequested configuration. Present only when requested with\ninclude=AVAILABILITY, which also requires `product`, and omitted\nentirely when the configuration is unavailable everywhere.\n", "items": { "$ref": "#/components/schemas/DataCenterAvailability" } }, "cudaVersions": { "type": "array", "description": "CUDA versions offered by machines with this GPU type, each tagged\nwith current capacity. Present only when requested with\ninclude=AVAILABILITY, and scoped by the same filters as\n`availability` (`count`, `cloud`, `product`, and whichever of\n`cudaVersions` / `minCudaVersion` was supplied).\n\nMachines that report no CUDA version are skipped, so this property\nis absent entirely for a GPU type with none — AMD, for instance.\nTreat a missing `cudaVersions` the same as an empty one. A version\nabsent from a populated list is not offered for this GPU type.\n", "items": { "$ref": "#/components/schemas/CudaVersionAvailability" } } } }, "AvailabilityLevel": { "type": "string", "description": "Catalog stock availability level.", "enum": [ "NONE", "LOW", "MEDIUM", "HIGH" ] }, "Product": { "type": "string", "description": "Catalog product availability context. Availability is product-specific, so this is required whenever availability is requested.", "enum": [ "POD", "CLUSTER", "SERVERLESS" ] }, "CpuProduct": { "type": "string", "description": "CPU catalog product availability context. Availability is product-specific, so this is required whenever availability is requested.", "enum": [ "POD", "SERVERLESS" ] }, "CatalogInclude": { "type": "string", "description": "Catalog include expansion. Only AVAILABILITY is supported today; additional include values may be added in the future.", "enum": [ "AVAILABILITY" ] }, "DataCenterInclude": { "type": "string", "description": "Data center catalog availability expansion.", "enum": [ "GPU_AVAILABILITY", "CPU_AVAILABILITY" ] }, "GpuCloudFilter": { "type": "string", "description": "GPU availability cloud filter.", "enum": [ "SECURE", "COMMUNITY" ] }, "VolumeType": { "type": "string", "description": "Data center network volume storage type.", "enum": [ "STANDARD", "HIGH_PERFORMANCE" ] }, "CatalogResourceAvailability": { "type": "object", "required": [ "id", "name", "availability" ], "properties": { "id": { "type": "string", "description": "Catalog resource identifier.", "examples": [ "NVIDIA GeForce RTX 4090" ] }, "name": { "type": "string", "description": "Human-readable catalog resource name.", "examples": [ "RTX 4090" ] }, "availability": { "$ref": "#/components/schemas/AvailabilityLevel" } } }, "DataCenterAvailability": { "type": "object", "required": [ "id", "name", "availability" ], "properties": { "id": { "type": "string", "description": "Data center identifier.", "examples": [ "US-CA-2" ] }, "name": { "type": "string", "description": "Human-readable data center name.", "examples": [ "US California 2" ] }, "availability": { "$ref": "#/components/schemas/AvailabilityLevel" } } }, "CudaVersionAvailability": { "type": "object", "required": [ "version", "available" ], "properties": { "version": { "type": "string", "pattern": "^\\d+\\.\\d+$", "description": "CUDA version as `major.minor`, suitable for `gpu.allowedCudaVersions` on pod create.", "examples": [ "12.8" ] }, "available": { "type": "boolean", "description": "True when at least one machine on this CUDA version has free capacity now. False means the version is offered for this GPU type but is currently full, so a pod constrained to it will fail on capacity.", "examples": [ true ] } } }, "ListGpuTypesResponse": { "type": "object", "required": [ "gpus" ], "properties": { "gpus": { "type": "array", "items": { "$ref": "#/components/schemas/GpuType" } } } }, "CpuType": { "type": "object", "required": [ "id", "name", "group", "vcpu", "ramGbPerVcpu", "price" ], "properties": { "id": { "type": "string", "description": "CPU flavor identifier (use in cpu.id for pod creation)", "examples": [ "cpu5c" ] }, "name": { "type": "string", "description": "Human-readable flavor name", "examples": [ "Compute-Optimized" ] }, "group": { "type": "string", "description": "CPU generation group", "examples": [ "Gen 5" ] }, "vcpu": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "integer", "examples": [ 2 ] }, "max": { "type": "integer", "examples": [ 32 ] } } }, "ramGbPerVcpu": { "type": "number", "format": "float", "description": "GB of RAM allocated per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total RAM\nfor an instance of this flavor. May be fractional.\n", "examples": [ 2.5 ] }, "price": { "type": "object", "required": [ "securePerVcpu", "serverlessPerVcpu" ], "properties": { "securePerVcpu": { "type": "number", "format": "float", "description": "Price for secure pods per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", "examples": [ 0.04 ] }, "serverlessPerVcpu": { "type": "number", "format": "float", "description": "Price for serverless per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", "examples": [ 0.03 ] } } }, "availability": { "description": "Overall CPU availability for the requested `product` contexts. Present only when requested with include=AVAILABILITY, which also requires `product`.", "$ref": "#/components/schemas/AvailabilityLevel" }, "dataCenters": { "type": "array", "description": "Per-datacenter CPU availability for the requested `product`\ncontexts, listing only the datacenters that offer this CPU flavor.\nPresent only when requested with include=AVAILABILITY, which also\nrequires `product`, and omitted entirely when the flavor is\nunavailable everywhere.\n", "items": { "$ref": "#/components/schemas/DataCenterAvailability" } } } }, "ListCpuTypesResponse": { "type": "object", "required": [ "cpus" ], "properties": { "cpus": { "type": "array", "items": { "$ref": "#/components/schemas/CpuType" } } } }, "DataCenter": { "type": "object", "required": [ "id", "name", "region", "networkVolumeTypes", "compliance", "globalNetwork" ], "properties": { "id": { "type": "string", "examples": [ "US-TX-3" ] }, "name": { "type": "string", "examples": [ "US Texas 3" ] }, "region": { "$ref": "#/components/schemas/DataCenterRegion" }, "globalNetwork": { "type": "boolean", "description": "Whether this data center supports global networking (private cross-datacenter pod-to-pod network).", "examples": [ true ] }, "networkVolumeTypes": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeType" }, "description": "Network volume tiers this DC supports. Empty = none." }, "compliance": { "type": "array", "description": "Compliance certifications held by this data center", "items": { "$ref": "#/components/schemas/Compliance" }, "examples": [ [ "GDPR", "ISO_IEC_27001", "SOC_2_TYPE_2" ] ] }, "gpuAvailability": { "type": "array", "description": "Availability of each GPU this data center offers. Present only when\nrequested with include=GPU_AVAILABILITY, and omitted entirely when\nthe data center offers no GPUs.\n", "items": { "$ref": "#/components/schemas/CatalogResourceAvailability" } }, "cpuAvailability": { "type": "array", "description": "Availability of each CPU flavor this data center offers. Present\nonly when requested with include=CPU_AVAILABILITY, and omitted\nentirely when the data center offers no CPU flavors.\n", "items": { "$ref": "#/components/schemas/CatalogResourceAvailability" } } } }, "DataCenterRegion": { "type": "string", "description": "Continental region containing the data center.", "examples": [ "EUROPE" ], "enum": [ "NORTH_AMERICA", "SOUTH_AMERICA", "EUROPE", "ASIA", "MIDDLE_EAST", "AFRICA", "OCEANIA", "ANTARCTICA", "UNKNOWN" ] }, "Compliance": { "type": "string", "description": "Compliance certifications.", "enum": [ "GDPR", "ISO_IEC_27001", "ISO_14001", "PCI_DSS", "HITRUST", "SOC_1_TYPE_2", "SOC_2_TYPE_2", "SOC_3_TYPE_2", "ITAR", "FISMA_HIGH", "HIPAA", "RENEWABLE" ] }, "ListDataCentersResponse": { "type": "object", "required": [ "dataCenters" ], "properties": { "dataCenters": { "type": "array", "items": { "$ref": "#/components/schemas/DataCenter" } } } }, "CostCenter": { "type": "object", "required": [ "id", "value" ], "properties": { "id": { "type": "string", "examples": [ "clz1x9k4a0000qw3h8s7d2f1g" ] }, "value": { "type": "string", "description": "Cost center name exactly as stored, so it matches billing breakdowns.", "examples": [ "team-ml" ] } } }, "ResourceCostCenter": { "description": "Cost center this resource's spend is attributed to. Absent when the resource is not attributed to a cost center, or when the caller lacks permission to view cost centers. Managed through `/v2/cost-centers`.", "allOf": [ { "$ref": "#/components/schemas/CostCenter" } ] }, "ListCostCentersResponse": { "type": "object", "required": [ "costCenters", "pagination" ], "properties": { "costCenters": { "type": "array", "items": { "$ref": "#/components/schemas/CostCenter" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ListCostCenterResourcesResponse": { "type": "object", "required": [ "resources", "pagination" ], "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/CostCenterResource" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ResourceType": { "type": "string", "description": "Kind of resource a cost center or tag can be attached to.", "x-enum-varnames": [ "ResourceTypePod", "ResourceTypeCluster", "ResourceTypeServerlessEndpoint", "ResourceTypeNetworkVolume" ], "enum": [ "POD", "CLUSTER", "SERVERLESS_ENDPOINT", "NETWORK_VOLUME" ] }, "CostCenterResource": { "type": "object", "additionalProperties": false, "required": [ "id", "type" ], "properties": { "id": { "type": "string", "minLength": 1, "examples": [ "p9k2m4n6q8" ] }, "type": { "$ref": "#/components/schemas/ResourceType" } } }, "CreateCostCenterRequest": { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^\\s*\\S", "description": "Leading and trailing whitespace is trimmed.", "examples": [ "team-ml" ] }, "resources": { "type": "array", "description": "Resources to attribute to the new cost center.", "maxItems": 100, "items": { "$ref": "#/components/schemas/CostCenterResource" } } } }, "UpdateCostCenterRequest": { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^\\s*\\S", "description": "Leading and trailing whitespace is trimmed.", "examples": [ "team-ml-eu" ] } } }, "TagReference": { "type": "object", "required": [ "id", "key", "value" ], "properties": { "id": { "type": "string", "description": "ID of the tag itself, shared by every resource it is attached to.", "examples": [ "clz1x9k4a0000qw3h8s7d2f1g" ] }, "key": { "type": "string", "examples": [ "env" ] }, "value": { "type": "string", "description": "May be empty.", "examples": [ "dev" ] } } }, "ResourceTags": { "type": "array", "description": "The tags on this resource that are visible to the caller. Keys and values are returned exactly as stored. Tags under the reserved `runpod:` prefix, such as the cost center, are never listed here. Absent when the resource's tags are unavailable to the caller; an empty array means none are visible.", "items": { "$ref": "#/components/schemas/TagReference" } }, "ResourceFilters": { "type": "object", "additionalProperties": false, "description": "An empty object, or an empty `tags` array, filters nothing.", "properties": { "tags": { "type": "array", "maxItems": 25, "description": "Conditions on the resource's tags. A resource must match every condition; repeating a key adds a condition rather than widening the first one. At most 25, the most tags one resource can carry.", "items": { "$ref": "#/components/schemas/TagCondition" } } } }, "TagCondition": { "type": "object", "additionalProperties": false, "required": [ "key" ], "properties": { "key": { "$ref": "#/components/schemas/TagKey" }, "values": { "type": "array", "maxItems": 100, "description": "Matches a tag under `key` with any one of these values, compared exactly. Omitted or empty, the condition only requires the key to be present. `\"\"` matches a tag whose value is empty. At most 100.", "items": { "type": "string", "maxLength": 191 }, "examples": [ [ "dev", "prod" ] ] } } }, "TagKey": { "type": "string", "minLength": 1, "maxLength": 191, "pattern": "[^\\t-\\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]", "not": { "pattern": "^[\\t-\\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*[Rr][Uu][Nn][Pp][Oo][Dd]:" }, "description": "Tag key, 1–191 characters as sent, with at least one that is not whitespace. Leading and trailing whitespace is ignored. Keys under the reserved `runpod:` prefix, in any letter case, are rejected.", "examples": [ "env" ] }, "Tag": { "type": "object", "required": [ "id", "key", "value", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Shared by every resource the tag is attached to.", "examples": [ "clz1x9k4a0000qw3h8s7d2f1g" ] }, "key": { "type": "string", "description": "Returned exactly as stored.", "examples": [ "env" ] }, "value": { "type": "string", "description": "Returned exactly as stored. May be empty.", "examples": [ "dev" ] }, "createdAt": { "type": "string", "format": "date-time", "examples": [ "2026-11-04T09:00:00Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "examples": [ "2026-11-04T09:00:00Z" ] } } }, "ListTagsResponse": { "type": "object", "required": [ "tags", "pagination" ], "properties": { "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ListTagResourcesResponse": { "type": "object", "required": [ "resources", "pagination" ], "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/CostCenterResource" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "CreateTagRequest": { "type": "object", "additionalProperties": false, "required": [ "key", "value" ], "properties": { "key": { "$ref": "#/components/schemas/TagKey" }, "value": { "$ref": "#/components/schemas/TagValue" }, "resources": { "type": "array", "description": "Existing resources to attach the new tag to.", "maxItems": 100, "items": { "$ref": "#/components/schemas/CostCenterResource" } } } }, "UpdateTagRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "The fields to change; omitted fields are unchanged. Resources the tag is attached to stay attached.", "properties": { "key": { "$ref": "#/components/schemas/TagKey" }, "value": { "$ref": "#/components/schemas/TagValue" } } }, "TagValue": { "type": "string", "maxLength": 191, "description": "Tag value, at most 191 characters. May be empty. Stored exactly as sent, whitespace included.", "examples": [ "dev" ] }, "AuditLog": { "type": "object", "description": "One recorded action on the account.", "required": [ "actorId", "email", "resourceType", "resourceId", "action", "value", "timestamp" ], "properties": { "actorId": { "type": [ "string", "null" ], "description": "ID of the user who performed the action. Null when the action was not attributable to a user.", "examples": [ "user_id_abc_123" ] }, "email": { "type": [ "string", "null" ], "description": "Email of the actor when the action was recorded. Null when unknown.", "examples": [ "actor@example.com" ] }, "resourceType": { "type": "string", "description": "Kind of resource the action applied to, as recorded at write time. Not an enum: values are free-form, mostly lower camel case, and new kinds appear without an API version change. Current writers record values such as `pod`, `apiKey`, `sharedApiKey`, `secret`, `costCenter`, `paymentMethod`, `billingAccount`, `registryCredential`, `organization` and `group`, and `unknown` when the writer recorded no kind.", "examples": [ "pod", "apiKey", "costCenter" ] }, "resourceId": { "type": "string", "description": "ID of the affected resource. Empty when the action was not about one resource; a bulk action lists every affected ID, comma-separated.", "examples": [ "abc123" ] }, "action": { "type": "string", "description": "Name of the action, as recorded at write time. Not an enum: values are free-form, mostly lower case verbs, and new actions appear without an API version change. Current writers record values such as `create`, `update`, `delete`, `rename`, `lock`, `unlock`, `start`, `reset`, `add` and `setBillingMode`.", "examples": [ "create", "delete", "rename" ] }, "value": { "type": [ "string", "null" ], "description": "Details of the change as a JSON-encoded string. The structure varies by action; parse it as JSON for a structured view. A bulk action split across several entries adds an `auditChunk` object with `index` and `of`. Null when the action recorded no details.", "examples": [ "{\"status\":\"TERMINATED\"}", "{\"name\":\"training-run-7\"}", "{\"id\":\"sec_789\",\"name\":\"HF_TOKEN\",\"sharedWithOrganization\":true}" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the action happened (UTC, whole seconds).", "examples": [ "2026-09-02T00:00:00Z" ] } } }, "ListAuditLogsResponse": { "type": "object", "required": [ "auditLogs", "pagination" ], "properties": { "auditLogs": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "BillingTimeRange": { "type": "object", "description": "Half-open time range [startTime, endTime) in RFC 3339. On a record it is the time bucket; on a query echo it is the resolved window.\n", "required": [ "startTime", "endTime" ], "properties": { "startTime": { "type": "string", "format": "date-time", "description": "Start of the range, inclusive (RFC 3339).", "examples": [ "2026-06-01T00:00:00Z" ] }, "endTime": { "type": "string", "format": "date-time", "description": "End of the range, exclusive (RFC 3339).", "examples": [ "2026-06-02T00:00:00Z" ] } } }, "BillingBucketSize": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ], "x-enum-varnames": [ "BillingBucketSizeHour", "BillingBucketSizeDay", "BillingBucketSizeWeek", "BillingBucketSizeMonth", "BillingBucketSizeYear" ], "default": "day", "description": "Length of each billing time bucket.", "examples": [ "day" ] }, "BillingMode": { "type": "string", "enum": [ "PREPAID", "POSTPAID" ], "description": "PREPAID accounts spend from the balance. POSTPAID accounts are invoiced, so a low balance doesn't stop them.", "examples": [ "PREPAID" ] }, "Balance": { "type": "object", "required": [ "balanceAmount", "billingMode" ], "properties": { "balanceAmount": { "type": "number", "format": "double", "description": "Account balance in USD. On a prepaid account, new Pods and workers are refused when it runs out.", "examples": [ 42.18 ] }, "billingMode": { "$ref": "#/components/schemas/BillingMode" } } }, "BillingAmounts": { "type": "object", "description": "Total spend across all billable Runpod resources with each cost component broken out, fully prefixed by resource. Backs the aggregate record's amounts and the metadata totals. Serverless amounts are inclusive of platform charges.\n", "required": [ "totalAmount", "podGpuAmount", "podCpuAmount", "podDiskAmount", "serverlessGpuAmount", "serverlessCpuAmount", "serverlessDiskAmount", "serverlessFeeAmount", "storageStandardAmount", "storageHighPerformanceAmount", "endpointAmount", "clusterGpuAmount", "clusterDiskAmount", "clusterNetworkingAmount" ], "properties": { "totalAmount": { "type": "number", "format": "double", "description": "Total cost in USD for the bucket across all resources.", "examples": [ 42.34 ] }, "podGpuAmount": { "type": "number", "format": "double", "description": "GPU pod compute cost in USD for the bucket." }, "podCpuAmount": { "type": "number", "format": "double", "description": "CPU pod compute cost in USD for the bucket." }, "podDiskAmount": { "type": "number", "format": "double", "description": "Pod disk cost in USD for the bucket." }, "serverlessGpuAmount": { "type": "number", "format": "double", "description": "Serverless GPU compute cost in USD for the bucket." }, "serverlessCpuAmount": { "type": "number", "format": "double", "description": "Serverless CPU compute cost in USD for the bucket." }, "serverlessDiskAmount": { "type": "number", "format": "double", "description": "Serverless disk cost in USD for the bucket." }, "serverlessFeeAmount": { "type": "number", "format": "double", "deprecated": true, "description": "Unused and always 0. Platform charges are included in the serverless compute amounts.\n" }, "storageStandardAmount": { "type": "number", "format": "double", "description": "Standard network volume storage cost in USD for the bucket." }, "storageHighPerformanceAmount": { "type": "number", "format": "double", "description": "High-performance network volume storage cost in USD for the bucket." }, "endpointAmount": { "type": "number", "format": "double", "description": "Runpod public endpoint cost in USD for the bucket." }, "clusterGpuAmount": { "type": "number", "format": "double", "description": "Cluster GPU compute cost in USD for the bucket." }, "clusterDiskAmount": { "type": "number", "format": "double", "description": "Cluster disk cost in USD for the bucket." }, "clusterNetworkingAmount": { "type": "number", "format": "double", "description": "Cluster inter-node networking cost in USD for the bucket." } } }, "BillingRecord": { "description": "A single time-bucketed record of total spend across all billable Runpod resources, with each cost component broken out. Returned by GET /v2/billing.\n", "allOf": [ { "$ref": "#/components/schemas/BillingTimeRange" }, { "$ref": "#/components/schemas/BillingAmounts" } ] }, "PodBillingAmounts": { "type": "object", "description": "Pod cost components covering both GPU and CPU pods. Backs a record's amounts and the metadata totals.\n", "required": [ "totalAmount", "gpuAmount", "cpuAmount", "diskAmount" ], "properties": { "totalAmount": { "type": "number", "format": "double", "description": "Total pod cost in USD for the bucket.", "examples": [ 12.34 ] }, "gpuAmount": { "type": "number", "format": "double", "description": "GPU pod compute cost in USD for the bucket." }, "cpuAmount": { "type": "number", "format": "double", "description": "CPU pod compute cost in USD for the bucket." }, "diskAmount": { "type": "number", "format": "double", "description": "Pod disk cost in USD for the bucket." } } }, "PodBillingRecord": { "description": "A single time-bucketed pod billing record, covering both GPU and CPU pods. Returned by GET /v2/billing/pods.\n", "allOf": [ { "$ref": "#/components/schemas/BillingTimeRange" }, { "$ref": "#/components/schemas/PodBillingAmounts" }, { "type": "object", "required": [ "podId" ], "properties": { "podId": { "type": "string", "description": "The pod this record bills. When the podId filter is set every record carries that id; otherwise one record is emitted per pod per bucket.\n", "examples": [ "pod_abc123" ] } } } ] }, "ServerlessBillingAmounts": { "type": "object", "description": "Serverless cost components, inclusive of platform charges. Backs a record's amounts and the metadata totals.\n", "required": [ "totalAmount", "gpuAmount", "cpuAmount", "diskAmount", "feeAmount" ], "properties": { "totalAmount": { "type": "number", "format": "double", "description": "Total serverless cost in USD for the bucket.", "examples": [ 8.9 ] }, "gpuAmount": { "type": "number", "format": "double", "description": "Serverless GPU compute cost in USD for the bucket." }, "cpuAmount": { "type": "number", "format": "double", "description": "Serverless CPU compute cost in USD for the bucket." }, "diskAmount": { "type": "number", "format": "double", "description": "Serverless disk cost in USD for the bucket." }, "feeAmount": { "type": "number", "format": "double", "deprecated": true, "description": "Unused and always 0. Platform charges are included in the GPU and CPU amounts.\n" } } }, "ServerlessBillingRecord": { "description": "A single time-bucketed serverless billing record. Returned by GET /v2/billing/serverless.\n", "allOf": [ { "$ref": "#/components/schemas/BillingTimeRange" }, { "$ref": "#/components/schemas/ServerlessBillingAmounts" }, { "type": "object", "required": [ "serverlessId" ], "properties": { "serverlessId": { "type": "string", "description": "The serverless endpoint this record bills. When the serverlessId filter is set every record carries that id; otherwise one record is emitted per serverless endpoint per bucket.\n", "examples": [ "ep_abc123" ] } } } ] }, "EndpointBillingAmounts": { "type": "object", "description": "Runpod public endpoint cost. Backs a record's amounts and the metadata totals.\n", "required": [ "totalAmount" ], "properties": { "totalAmount": { "type": "number", "format": "double", "description": "Total public endpoint cost in USD for the bucket.", "examples": [ 3.21 ] } } }, "EndpointBillingRecord": { "description": "A single time-bucketed Runpod public endpoint billing record. Returned by GET /v2/billing/endpoints.\n", "allOf": [ { "$ref": "#/components/schemas/BillingTimeRange" }, { "$ref": "#/components/schemas/EndpointBillingAmounts" } ] }, "NetworkVolumeBillingAmounts": { "type": "object", "description": "Network volume storage cost, split into standard and high-performance. Backs a record's amounts and the metadata totals.\n", "required": [ "totalAmount", "standardAmount", "highPerformanceAmount" ], "properties": { "totalAmount": { "type": "number", "format": "double", "description": "Total network volume cost in USD for the bucket, across standard and high-performance storage.\n", "examples": [ 5.79 ] }, "standardAmount": { "type": "number", "format": "double", "description": "Standard storage cost in USD for the bucket." }, "highPerformanceAmount": { "type": "number", "format": "double", "description": "High-performance storage cost in USD for the bucket." } } }, "NetworkVolumeBillingRecord": { "description": "A single time-bucketed network volume billing record, split into standard and high-performance storage. Returned by GET /v2/billing/network-volumes.\n", "allOf": [ { "$ref": "#/components/schemas/BillingTimeRange" }, { "$ref": "#/components/schemas/NetworkVolumeBillingAmounts" }, { "type": "object", "required": [ "networkVolumeId" ], "properties": { "networkVolumeId": { "type": "string", "description": "The network volume this record bills. When the networkVolumeId filter is set every record carries that id; otherwise one record is emitted per network volume per bucket.\n", "examples": [ "vol_abc123" ] } } } ] }, "ClusterBillingAmounts": { "type": "object", "description": "Cluster cost components (GPU-only, no CPU). Backs a record's amounts and the metadata totals.\n", "required": [ "totalAmount", "gpuAmount", "diskAmount", "networkingAmount" ], "properties": { "totalAmount": { "type": "number", "format": "double", "description": "Total Instant Cluster cost in USD for the bucket.", "examples": [ 99.0 ] }, "gpuAmount": { "type": "number", "format": "double", "description": "Cluster GPU compute cost in USD for the bucket." }, "diskAmount": { "type": "number", "format": "double", "description": "Cluster disk cost in USD for the bucket." }, "networkingAmount": { "type": "number", "format": "double", "description": "Cluster inter-node networking cost in USD for the bucket." } } }, "ClusterBillingRecord": { "description": "A single time-bucketed cluster billing record; clusters are GPU-only (no CPU component). Returned by GET /v2/billing/clusters.\n", "allOf": [ { "$ref": "#/components/schemas/BillingTimeRange" }, { "$ref": "#/components/schemas/ClusterBillingAmounts" }, { "type": "object", "required": [ "clusterId" ], "properties": { "clusterId": { "type": "string", "description": "The cluster this record bills. When the clusterId filter is set every record carries that id; otherwise one record is emitted per cluster per bucket.\n", "examples": [ "cluster_abc123" ] } } } ] }, "BillingQuery": { "description": "Resolved query window and granularity (routes without a filter).", "allOf": [ { "$ref": "#/components/schemas/BillingTimeRange" }, { "type": "object", "required": [ "bucketSize" ], "properties": { "bucketSize": { "$ref": "#/components/schemas/BillingBucketSize" } } } ] }, "PodBillingQuery": { "allOf": [ { "$ref": "#/components/schemas/BillingQuery" }, { "type": "object", "properties": { "podId": { "type": [ "string", "null" ], "description": "The podId filter applied, if any." } } } ] }, "ServerlessBillingQuery": { "allOf": [ { "$ref": "#/components/schemas/BillingQuery" }, { "type": "object", "properties": { "serverlessId": { "type": [ "string", "null" ], "description": "The serverlessId filter applied, if any." } } } ] }, "NetworkVolumeBillingQuery": { "allOf": [ { "$ref": "#/components/schemas/BillingQuery" }, { "type": "object", "properties": { "networkVolumeId": { "type": [ "string", "null" ], "description": "The networkVolumeId filter applied, if any." } } } ] }, "ClusterBillingQuery": { "allOf": [ { "$ref": "#/components/schemas/BillingQuery" }, { "type": "object", "properties": { "clusterId": { "type": [ "string", "null" ], "description": "The clusterId filter applied, if any." } } } ] }, "BillingMetadata": { "type": "object", "required": [ "query", "recordCount", "totals" ], "properties": { "query": { "$ref": "#/components/schemas/BillingQuery" }, "recordCount": { "type": "integer", "description": "Number of records returned." }, "totals": { "$ref": "#/components/schemas/BillingAmounts" } } }, "PodBillingMetadata": { "type": "object", "required": [ "query", "recordCount", "uniquePodCount", "totals" ], "properties": { "query": { "$ref": "#/components/schemas/PodBillingQuery" }, "recordCount": { "type": "integer", "description": "Number of records returned (buckets times distinct pods)." }, "uniquePodCount": { "type": "integer", "description": "Number of distinct pods the records span." }, "totals": { "$ref": "#/components/schemas/PodBillingAmounts" } } }, "ServerlessBillingMetadata": { "type": "object", "required": [ "query", "recordCount", "uniqueServerlessCount", "totals" ], "properties": { "query": { "$ref": "#/components/schemas/ServerlessBillingQuery" }, "recordCount": { "type": "integer", "description": "Number of records returned (buckets times distinct endpoints)." }, "uniqueServerlessCount": { "type": "integer", "description": "Number of distinct serverless endpoints the records span." }, "totals": { "$ref": "#/components/schemas/ServerlessBillingAmounts" } } }, "EndpointBillingMetadata": { "type": "object", "required": [ "query", "recordCount", "totals" ], "properties": { "query": { "$ref": "#/components/schemas/BillingQuery" }, "recordCount": { "type": "integer" }, "totals": { "$ref": "#/components/schemas/EndpointBillingAmounts" } } }, "NetworkVolumeBillingMetadata": { "type": "object", "required": [ "query", "recordCount", "uniqueNetworkVolumeCount", "totals" ], "properties": { "query": { "$ref": "#/components/schemas/NetworkVolumeBillingQuery" }, "recordCount": { "type": "integer", "description": "Number of records returned (buckets times distinct volumes)." }, "uniqueNetworkVolumeCount": { "type": "integer", "description": "Number of distinct network volumes the records span." }, "totals": { "$ref": "#/components/schemas/NetworkVolumeBillingAmounts" } } }, "ClusterBillingMetadata": { "type": "object", "required": [ "query", "recordCount", "uniqueClusterCount", "totals" ], "properties": { "query": { "$ref": "#/components/schemas/ClusterBillingQuery" }, "recordCount": { "type": "integer", "description": "Number of records returned (buckets times distinct clusters)." }, "uniqueClusterCount": { "type": "integer", "description": "Number of distinct clusters the records span." }, "totals": { "$ref": "#/components/schemas/ClusterBillingAmounts" } } }, "ListBillingResponse": { "type": "object", "description": "Aggregated billing records across all Runpod resources.", "required": [ "records", "metadata" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/BillingRecord" } }, "metadata": { "$ref": "#/components/schemas/BillingMetadata" } } }, "ListPodBillingResponse": { "type": "object", "description": "Billing records for pods.", "required": [ "records", "metadata" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/PodBillingRecord" } }, "metadata": { "$ref": "#/components/schemas/PodBillingMetadata" } } }, "ListServerlessBillingResponse": { "type": "object", "description": "Billing records for serverless.", "required": [ "records", "metadata" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessBillingRecord" } }, "metadata": { "$ref": "#/components/schemas/ServerlessBillingMetadata" } } }, "ListEndpointBillingResponse": { "type": "object", "description": "Time-bucketed Runpod public endpoint billing records plus metadata for the resolved query, record count, and total endpoint amount.\n", "required": [ "records", "metadata" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointBillingRecord" } }, "metadata": { "$ref": "#/components/schemas/EndpointBillingMetadata" } } }, "ListNetworkVolumeBillingResponse": { "type": "object", "description": "Time-bucketed network volume billing records plus metadata for the resolved query, record count, distinct volume count, and storage totals.\n", "required": [ "records", "metadata" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkVolumeBillingRecord" } }, "metadata": { "$ref": "#/components/schemas/NetworkVolumeBillingMetadata" } } }, "ListClusterBillingResponse": { "type": "object", "description": "Time-bucketed Cluster billing records plus metadata for the resolved query, record count, distinct cluster count, and compute totals.\n", "required": [ "records", "metadata" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterBillingRecord" } }, "metadata": { "$ref": "#/components/schemas/ClusterBillingMetadata" } } }, "ErrorResponse": { "type": "object", "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "description": "Short human-readable summary", "examples": [ "Not Found" ] }, "status": { "type": "integer", "description": "HTTP status code", "examples": [ 404 ] }, "detail": { "type": "string", "description": "Human-readable explanation", "examples": [ "pod not found" ] }, "errors": { "type": "array", "description": "Individual request-validation failures.", "items": { "type": "string" }, "examples": [ [ "$: additional properties 'bogus' not allowed" ] ] } } }, "RateLimitHeader": { "type": "string", "description": "Live per-window quota state. Optional — omitted for rate-limit-exempt\ncallers.\n\nA structured-field list with one member per window (`minute`, `hour`,\n`day`), each carrying the remaining request count `r` and seconds until\nthe window resets `t` (at least 1). Windows are fixed and aligned to the\nclock, not sliding. Returned on responses to authenticated requests,\nnot only on 429s.\n", "examples": [ "\"minute\";r=0;t=12, \"hour\";r=2800;t=1812, \"day\";r=49500;t=45012" ] }, "RateLimitPolicyHeader": { "type": "string", "description": "Static per-window quota policy. Optional — omitted for rate-limit-exempt\ncallers.\n\nA structured-field list with one member per window (`minute`, `hour`,\n`day`), each carrying the quota `q` and the window length in seconds `w`.\nReturned on responses to authenticated requests, not only on 429s.\n\nLimits are per user, and every `/v2` route counts toward the same\nlimits; creating pods has no separate limit. Read the current quotas from\nthis header instead of hard-coding them, because they can change and some\naccounts have higher limits. A 429 only slows you down: wait for the\n`Retry-After` time and retry. Your account isn't suspended.\n", "examples": [ "\"minute\";q=180;w=60, \"hour\";q=3600;w=3600, \"day\";q=43200;w=86400" ] } } }, "paths": { "/v2/organization": { "get": { "operationId": "getOrganization", "x-runpod-scope": "membership:read", "summary": "Get your current organization", "x-mint": { "metadata": { "description": "Retrieve your current Runpod organization." } }, "description": "Returns the authenticated caller's current organization. Organization context comes from the caller's membership; no selector is required. Returns 404 when the caller does not belong to an organization, or 403 when organizations are unavailable to the caller.", "tags": [ "Organization" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" }, "examples": { "organization": { "summary": "Current organization", "value": { "id": "org_id_abc_123", "name": "my-org", "role": { "id": "builtin:dev", "type": "builtin", "name": "Developer" }, "groups": [ { "id": "group_id_abc_123", "name": "Engineering" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/groups": { "get": { "operationId": "listOrganizationGroups", "x-runpod-scope": "membership:read", "summary": "List groups in your current organization", "x-mint": { "metadata": { "description": "List groups in your current organization with cursor pagination." } }, "description": "Returns groups without their members or roles, ordered by creation time descending and then ID descending for deterministic pagination.", "tags": [ "Organization" ], "parameters": [ { "name": "name", "in": "query", "required": false, "description": "Optional case-insensitive substring of the group name. An empty value applies no filter.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimitOrganizationGroups" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrganizationGroupsResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createOrganizationGroup", "x-runpod-scope": "membership:write", "summary": "Create a group in your current organization", "x-mint": { "metadata": { "description": "Create a named group in your current organization. Add members separately." } }, "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationGroupRequest" }, "examples": { "group": { "value": { "name": "Engineering" } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationGroup" }, "examples": { "group": { "value": { "id": "group_123", "name": "Engineering", "memberCount": 0, "createdAt": "2026-10-13T12:00:00Z", "updatedAt": "2026-10-13T12:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "409": { "description": "A group with this name already exists in the current organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/groups/{id}/members/{userId}": { "put": { "operationId": "addOrganizationGroupMember", "x-runpod-scope": "membership:write", "summary": "Add a member to a group", "x-mint": { "metadata": { "description": "Add an existing organization member to a group." } }, "description": "Adds the organization member to the group. The group and user must belong to the current organization. Adding an existing member is idempotent and returns the same no-content response.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Group ID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "userId", "in": "path", "required": true, "description": "Organization member user ID.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Member added, or already belongs to the group." }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "removeOrganizationGroupMember", "x-runpod-scope": "membership:write", "summary": "Remove a member from a group", "x-mint": { "metadata": { "description": "Remove an organization member from a group." } }, "description": "Removes the organization member from the group. The group and user must belong to the current organization. Returns 404 when the membership is absent, including repeated deletion, or when the group is unknown or belongs to another organization.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Group ID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "userId", "in": "path", "required": true, "description": "Organization member user ID.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Member removed." }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/groups/{id}/members": { "get": { "operationId": "listOrganizationGroupMembers", "x-runpod-scope": "membership:read", "summary": "List members of a group", "x-mint": { "metadata": { "description": "List members of a group with cursor pagination." } }, "description": "Members are ordered newest first by membership creation time, with a unique upstream tie-breaker. Returns 404 when the group does not exist in the current organization, or when the caller does not belong to an organization.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Group ID.", "schema": { "type": "string", "minLength": 1 } }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimitOrganizationGroups" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrganizationGroupMembersResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/groups/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Group ID.", "schema": { "type": "string", "minLength": 1 } } ], "get": { "operationId": "getOrganizationGroup", "x-runpod-scope": "membership:read", "summary": "Get a group in your current organization", "x-mint": { "metadata": { "description": "Get one group by ID from your current organization." } }, "description": "Returns the group without its members. Returns 404 when the ID is unknown or belongs to another organization, or when the caller does not belong to an organization.", "tags": [ "Organization" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationGroup" }, "examples": { "group": { "value": { "id": "group_123", "name": "Engineering", "memberCount": 3, "createdAt": "2026-10-13T12:00:00Z", "updatedAt": "2026-10-15T12:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateOrganizationGroup", "x-runpod-scope": "membership:write", "summary": "Rename a group in your current organization", "x-mint": { "metadata": { "description": "Rename a group in your current organization without changing its members." } }, "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationGroupRequest" }, "examples": { "group": { "value": { "name": "Research" } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationGroup" }, "examples": { "group": { "value": { "id": "group_123", "name": "Research", "memberCount": 3, "createdAt": "2026-10-13T12:00:00Z", "updatedAt": "2026-10-15T12:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "A group with this name already exists in the current organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteOrganizationGroup", "x-runpod-scope": "membership:write", "summary": "Delete a group in your current organization", "x-mint": { "metadata": { "description": "Delete a group and its group memberships without removing anyone from the organization." } }, "description": "Permanently deletes the group and its group memberships. Organization members are not removed. Returns 404 when the group does not exist in your current organization, including when it has already been deleted.", "tags": [ "Organization" ], "responses": { "204": { "description": "Deleted", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/account": { "get": { "operationId": "getAccount", "x-runpod-scope": "account:read", "summary": "Get your account", "x-mint": { "metadata": { "description": "Retrieve the ID and email of the Runpod account your API key belongs to." } }, "description": "Returns the account the API key belongs to.", "tags": [ "Account" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "examples": { "account": { "summary": "Successful response", "value": { "id": "user_2abc123", "email": "dev@example.com" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/account/limits": { "get": { "operationId": "getAccountLimits", "x-runpod-scope": "account:read", "summary": "Get account limits", "x-mint": { "metadata": { "description": "Read the spend rate limit, current spend rate, and resource limits that apply to your Runpod account before you deploy." } }, "description": "Returns the limits that apply to the account this request acts for. A create or resume that would go past a limit is refused. Not available for organizations (403).", "tags": [ "Account" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLimits" }, "examples": { "free": { "summary": "Account on the free plan", "value": { "spendRate": { "limit": 80, "current": 12.4 }, "serverlessWorkers": { "limit": 10 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/account/ssh-keys": { "get": { "operationId": "getSshKeys", "x-runpod-scope": "authentication:read", "summary": "List registered SSH public keys", "x-mint": { "metadata": { "description": "List the SSH public keys registered to your Runpod account and used to authenticate secure connections to newly created Pods." } }, "description": "Returns the account's registered SSH public keys — the keys provisioned into pods created with `startSsh` and used to authenticate the SSH connections reported in a pod's `ssh` block.", "tags": [ "Account" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKeys" }, "examples": { "keys": { "summary": "Successful response", "value": { "keys": [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILXGDN/SclOozk1xsDztpmhGiKkkrfQB9SKoO8dSIQQZ me@example.com" ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "updateSshKeys", "x-runpod-scope": "authentication:write", "summary": "Replace registered SSH public keys", "x-mint": { "metadata": { "description": "Replace all SSH public keys registered to your Runpod account, remove omitted keys, and apply the new set to subsequently created Pods." } }, "description": "Replaces the account's full set of registered SSH public keys. Existing keys not present in the request are removed; send `[]` to remove all keys. Keys take effect for pods created afterwards with `startSsh` — running pods are not updated.", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSshKeysRequest" }, "examples": { "replaceKeys": { "summary": "Register a single key", "value": { "keys": [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILXGDN/SclOozk1xsDztpmhGiKkkrfQB9SKoO8dSIQQZ me@example.com" ] } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK — the updated key set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKeys" }, "examples": { "keys": { "summary": "Successful response", "value": { "keys": [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILXGDN/SclOozk1xsDztpmhGiKkkrfQB9SKoO8dSIQQZ me@example.com" ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/users": { "get": { "operationId": "listOrganizationUsers", "x-runpod-scope": "membership:read", "summary": "List organization members", "x-mint": { "metadata": { "description": "List the members of your organization and the role each one holds." } }, "description": "Returns every member of the authenticated caller's organization with the role each holds. Any member can read the roster. The list is complete and takes no pagination parameters. Returns 404 when the caller does not belong to an organization, or 403 when organizations are unavailable to the caller.", "tags": [ "Organization" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrganizationUsersResponse" }, "examples": { "users": { "summary": "Organization members", "value": { "users": [ { "id": "user_id_abc_123", "email": "owner@example.com", "role": { "id": "builtin:admin", "type": "builtin", "name": "Admin" }, "groups": [] }, { "id": "user_id_def_456", "email": "member@example.com", "role": { "id": "builtin:dev", "type": "builtin", "name": "Developer" }, "groups": [ { "id": "group_id_abc_123", "name": "Engineering" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/users/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User identifier", "example": "user_id_abc_123" } ], "get": { "operationId": "getOrganizationUser", "x-runpod-scope": "membership:read", "summary": "Get an organization member", "x-mint": { "metadata": { "description": "Get one member of your organization by user ID." } }, "description": "Returns one member of the authenticated caller's organization by user ID, with the role they hold. Any member can read it. A user who is not a member, including one from another organization, returns 404. Returns 404 when the caller does not belong to an organization, or 403 when organizations are unavailable to the caller.", "tags": [ "Organization" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUser" }, "examples": { "user": { "summary": "Organization member", "value": { "id": "user_id_abc_123", "email": "owner@example.com", "role": { "id": "builtin:admin", "type": "builtin", "name": "Admin" }, "groups": [ { "id": "group_id_abc_123", "name": "Engineering" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateOrganizationUser", "x-runpod-scope": "membership:write", "summary": "Update an organization member", "x-mint": { "metadata": { "description": "Change a member's role, replace their groups, or both, by user ID." } }, "description": "Changes one member of the authenticated caller's organization by user ID: assigns a role, replaces their set of groups, or both, applied together or not at all. Send at least one field; an omitted field is left as it is, and an empty `groups` list removes the member from every group. Updating members requires the organization's member-management capability, which the built-in admin role holds; other members, and callers outside an organization, receive 403, as does a caller for whom organizations are unavailable. Returns 403 when the caller changes their own role or assigns a role granting a capability the caller lacks; 409 when the change would leave the organization without a member in the built-in admin role; and 404 when the user is not a member or the role or a group is unknown to the organization, with the detail naming which.", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationUserRequest" }, "examples": { "role": { "summary": "Assign a built-in role", "value": { "role": { "id": "builtin:dev" } } }, "groups": { "summary": "Replace the member's groups", "value": { "groups": [ { "id": "group_id_abc_123" } ] } }, "clearGroups": { "summary": "Remove the member from every group", "value": { "groups": [] } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUser" }, "examples": { "user": { "summary": "The member after the change", "value": { "id": "user_id_abc_123", "email": "member@example.com", "role": { "id": "builtin:dev", "type": "builtin", "name": "Developer" }, "groups": [ { "id": "group_id_abc_123", "name": "Engineering" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "The change would leave the organization without a member in the built-in admin role.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteOrganizationUser", "x-runpod-scope": "membership:write", "summary": "Remove an organization member", "x-mint": { "metadata": { "description": "Remove a member from your organization by user ID." } }, "description": "Removes one member from the authenticated caller's organization by user ID. Their group memberships end and the API keys attributed to them within the organization are revoked; the resources they created stay with the organization. Removing another member requires the organization's member-removal capability, which the built-in admin role holds; any member can remove themselves. The organization keeps at least one member with the built-in admin role, so removing the last one returns 409. A user who is not a member, including one from another organization, returns 404. A member without the capability removing someone else, a caller outside an organization, and a caller for whom organizations are unavailable receive 403.", "tags": [ "Organization" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Removed. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "The member holds the organization's only built-in admin role.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/invites": { "get": { "operationId": "listOrganizationInvites", "x-runpod-scope": "membership:read", "summary": "List pending organization invites", "x-mint": { "metadata": { "description": "List the pending invitations to your organization." } }, "description": "Returns the pending invitations to the authenticated caller's organization, newest first. Only unexpired invites are pending: an invite leaves the list once it is accepted, revoked or expired. The list is complete and takes no pagination parameters, because an organization's pending invites are capped. Reading invites requires the organization's invite-management capability, which the built-in admin role holds; other members receive 403. Returns 404 when the caller does not belong to an organization, or 403 when organizations are unavailable to the caller.", "tags": [ "Organization" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrganizationInvitesResponse" }, "examples": { "invites": { "summary": "Pending invites", "value": { "invites": [ { "id": "invite_id_abc_123", "email": "new-member@example.com", "role": { "id": "builtin:dev", "type": "builtin", "name": "Developer" }, "createdAt": "2026-10-01T09:00:00Z", "expiresAt": "2026-10-15T09:00:00Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createOrganizationInvite", "x-runpod-scope": "membership:write", "summary": "Invite a user to your organization", "x-mint": { "metadata": { "description": "Invite a user to your organization by email and choose the role they receive on joining." } }, "description": "Sends an invitation to join the authenticated caller's organization and returns the pending invite; `expiresAt` is when it lapses. The invitee receives an email carrying the acceptance link, which is never returned here. Returns 409 when the address already belongs to a member or to a pending invite, or when the organization has reached its pending-invite limit; 404 when the role is unknown to the organization; and 403 when the caller does not hold every capability the role grants. Inviting requires the organization's invite-management capability, which the built-in admin role holds; other members, and callers outside an organization, receive 403, as does a caller for whom organizations are unavailable.", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationInviteRequest" }, "examples": { "invite": { "summary": "Invite as a built-in role", "value": { "email": "new-member@example.com", "role": { "id": "builtin:dev" } } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvite" }, "examples": { "invite": { "summary": "Successful response", "value": { "id": "invite_id_abc_123", "email": "new-member@example.com", "role": { "id": "builtin:dev", "type": "builtin", "name": "Developer" }, "createdAt": "2026-10-01T09:00:00Z", "expiresAt": "2026-10-15T09:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "The address already belongs to an organization member or to a pending invite, or the organization has reached its pending-invite limit.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/invites/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invite identifier", "example": "invite_id_abc_123" } ], "get": { "operationId": "getOrganizationInvite", "x-runpod-scope": "membership:read", "summary": "Get a pending organization invite", "x-mint": { "metadata": { "description": "Get one pending invitation to your organization by ID." } }, "description": "Returns one pending invitation to the authenticated caller's organization. Only unexpired invites are pending: an invite that has expired, been accepted or been revoked returns 404, as does an ID from another organization. Reading invites requires the organization's invite-management capability, which the built-in admin role holds; other members receive 403. Returns 404 when the caller does not belong to an organization, or 403 when organizations are unavailable to the caller.", "tags": [ "Organization" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvite" }, "examples": { "invite": { "summary": "Pending invite", "value": { "id": "invite_id_abc_123", "email": "new-member@example.com", "role": { "id": "builtin:dev", "type": "builtin", "name": "Developer" }, "createdAt": "2026-10-01T09:00:00Z", "expiresAt": "2026-10-15T09:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteOrganizationInvite", "x-runpod-scope": "membership:write", "summary": "Cancel an organization invite", "x-mint": { "metadata": { "description": "Cancel a pending invitation to your organization so it can no longer be accepted." } }, "description": "Cancels one invitation to the authenticated caller's organization; the invitee can no longer accept it. Returns 404 when the ID is unknown to the caller's organization: never issued, already accepted, already cancelled, or issued by another organization. An expired invite can still be cancelled. Cancelling invites requires the organization's invite-management capability, which the built-in admin role holds; other members, and callers outside an organization, receive 403, as does a caller for whom organizations are unavailable.", "tags": [ "Organization" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Cancelled. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/roles": { "get": { "operationId": "listOrganizationRoles", "x-runpod-scope": "membership:read", "summary": "List organization roles", "x-mint": { "metadata": { "description": "List the built-in roles and your organization's custom roles, with the capabilities each grants." } }, "description": "Returns every role a member or invite of the authenticated caller's organization can hold: Runpod's built-in roles and the organization's custom roles, oldest first. The list is complete and takes no pagination parameters, because an organization's custom roles are capped. Returns 404 when the caller does not belong to an organization, or 403 when organizations are unavailable to the caller.", "tags": [ "Organization" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrganizationRolesResponse" }, "examples": { "roles": { "summary": "Built-in and custom roles", "value": { "roles": [ { "id": "builtin:dev", "name": "Dev", "type": "builtin", "capabilities": [ "POD:CREATE", "POD:VIEW" ] }, { "id": "cmcustomrole0001", "name": "Pod viewer", "type": "custom", "capabilities": [ "POD:VIEW" ], "createdAt": "2026-10-01T09:00:00Z", "updatedAt": "2026-10-02T09:00:00Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createOrganizationRole", "x-runpod-scope": "membership:write", "summary": "Create a custom organization role", "x-mint": { "metadata": { "description": "Create a custom role in your organization from a name and the capabilities it grants." } }, "description": "Creates a custom role in the authenticated caller's organization and returns it. Returns 409 when the organization already has a role with this name or has reached its custom-role limit; 422 when a capability is unknown or the name is reserved; and 403 when the caller does not hold every capability the role grants. Creating roles requires the organization's role-management capability, which the built-in admin role holds; other members, and callers outside an organization, receive 403, as does a caller for whom organizations are unavailable.", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRoleRequest" }, "examples": { "role": { "summary": "Read-only pod access", "value": { "name": "Pod viewer", "capabilities": [ "POD:VIEW" ] } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationRole" }, "examples": { "role": { "summary": "Successful response", "value": { "id": "cmcustomrole0001", "name": "Pod viewer", "type": "custom", "capabilities": [ "POD:VIEW" ], "createdAt": "2026-10-01T09:00:00Z", "updatedAt": "2026-10-01T09:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "The organization already has a role with this name, or has reached its custom-role limit.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/roles/capabilities": { "get": { "operationId": "getOrganizationRoleCapabilities", "x-runpod-scope": "membership:read", "summary": "List grantable role capabilities", "x-mint": { "metadata": { "description": "List the capabilities a custom role in your organization can grant." } }, "description": "Returns the capabilities a custom role can grant, grouped by family: each capability is a family and one of its verbs, written `FAMILY:VERB`. This is the set role creation accepts, not filtered to the caller's own access; saving a role also requires the caller to hold every capability it grants. `family` and `verb` narrow the result and apply together; with neither, the whole catalog is returned. Reading the catalog requires organization membership; other callers receive 403.", "tags": [ "Organization" ], "parameters": [ { "$ref": "#/components/parameters/OrganizationCapabilityFamilyFilter" }, { "$ref": "#/components/parameters/OrganizationCapabilityVerbFilter" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCapabilityCatalog" }, "examples": { "catalog": { "summary": "Pod and endpoint view verbs", "value": { "version": 1, "families": [ { "family": "POD", "verbs": [ "VIEW" ] }, { "family": "ENDPOINT", "verbs": [ "VIEW" ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/organization/roles/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Role identifier", "example": "cmcustomrole0001" } ], "get": { "operationId": "getOrganizationRole", "x-runpod-scope": "membership:read", "summary": "Get an organization role", "x-mint": { "metadata": { "description": "Get one built-in or custom role by ID, with the capabilities it grants." } }, "description": "Returns one role a member or invite of the authenticated caller's organization can hold: a built-in role, or one of the organization's custom roles. Returns 404 when the ID is unknown or names another organization's custom role, or when the caller does not belong to an organization; 403 when the caller may not view the organization's roles or organizations are unavailable to the caller.", "tags": [ "Organization" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationRole" }, "examples": { "custom": { "summary": "Custom role", "value": { "id": "cmcustomrole0001", "name": "Pod viewer", "type": "custom", "capabilities": [ "POD:VIEW" ], "createdAt": "2026-10-01T09:00:00Z", "updatedAt": "2026-10-02T09:00:00Z" } }, "builtin": { "summary": "Built-in role", "value": { "id": "builtin:dev", "name": "Dev", "type": "builtin", "capabilities": [ "POD:CREATE", "POD:VIEW" ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateOrganizationRole", "x-runpod-scope": "membership:write", "summary": "Update a custom organization role", "x-mint": { "metadata": { "description": "Rename a custom role in your organization or replace the capabilities it grants." } }, "description": "Changes a custom role's name, its capabilities, or both, and returns the role. Sent capabilities replace the whole grant set. Returns 400 for a built-in role, which cannot be changed; 404 when the ID is unknown or names another organization's role; 403 when the caller does not hold every capability the role grants, before or after the change; 409 when the organization already has a role with the new name; and 422 when a capability is unknown or the name is reserved. Updating roles requires the organization's role-management capability, which the built-in admin role holds; other members, and callers outside an organization, receive 403, as does a caller for whom organizations are unavailable.", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationRoleRequest" }, "examples": { "rename": { "summary": "Rename a role", "value": { "name": "Pod operator" } }, "capabilities": { "summary": "Replace a role's capabilities", "value": { "capabilities": [ "POD:USE", "POD:VIEW" ] } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationRole" }, "examples": { "role": { "summary": "Successful response", "value": { "id": "cmcustomrole0001", "name": "Pod operator", "type": "custom", "capabilities": [ "POD:USE", "POD:VIEW" ], "createdAt": "2026-10-01T09:00:00Z", "updatedAt": "2026-10-03T09:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "The organization already has a role with this name.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteOrganizationRole", "x-runpod-scope": "membership:write", "summary": "Delete a custom organization role", "x-mint": { "metadata": { "description": "Delete a custom role from your organization once no member or pending invite holds it." } }, "description": "Deletes a custom role from the authenticated caller's organization. Returns 409 while a member or a pending invite holds the role: reassign those members and cancel those invites first, since deleting never changes anyone's role. Expired invites do not block deletion. Returns 400 for a built-in role, which cannot be deleted; 404 when the ID is unknown, names another organization's role, or was already deleted. Deleting roles requires the organization's role-management capability, which the built-in admin role holds; other members, and callers outside an organization, receive 403, as does a caller for whom organizations are unavailable.", "tags": [ "Organization" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "A member or a pending invite still holds the role. The detail gives how many of each.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/account/secrets": { "get": { "operationId": "listSecrets", "x-runpod-scope": "secrets:read", "summary": "List secrets", "x-mint": { "metadata": { "description": "List encrypted secrets referenced by Runpod Pods, Serverless endpoints, and templates through environment variables. Secret values are never returned." } }, "description": "Returns the account's secrets — encrypted strings referenced from pod, serverless, and template environment variables with the `{{ RUNPOD_SECRET_ }}` placeholder syntax, substituted with the secret's value when the pod or worker boots. Secret values are write-only and are never returned.", "tags": [ "Account" ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "When provided, returns only the secret with this name (case-insensitive)." } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSecretsResponse" }, "examples": { "secrets": { "summary": "Successful response", "value": { "secrets": [ { "id": "2q9m7x4cavgd", "name": "hf-token", "description": "Hugging Face read token", "createdAt": "2026-08-01T12:00:00Z", "valueLastUpdatedAt": "2026-09-01T08:30:00Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createSecret", "x-runpod-scope": "secrets:write", "summary": "Create a secret", "x-mint": { "metadata": { "description": "Create an encrypted Runpod account secret that Pods, Serverless endpoints, and templates can reference from environment variables at boot." } }, "description": "Stores a new account-scoped encrypted string. `name` must be unique\nacross the account's secrets and is immutable; `value` is write-only\nand can never be read back through the API.\n\nUse the secret from pods, serverless endpoints, and templates by\nsetting an environment variable's value to\n`{{ RUNPOD_SECRET_ }}` — Runpod substitutes the stored value\nwhen the pod or worker boots.\n\nReturns `201` with the created secret's metadata, or `409` when the\nname is already taken.\n", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretRequest" }, "examples": { "secret": { "summary": "Secret with a description", "value": { "name": "hf-token", "value": "hf_********************************", "description": "Hugging Face read token" } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Secret" }, "examples": { "secret": { "summary": "Successful response", "value": { "id": "2q9m7x4cavgd", "name": "hf-token", "description": "Hugging Face read token", "createdAt": "2026-09-10T17:23:45Z", "valueLastUpdatedAt": "2026-09-10T17:23:45Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "409": { "description": "A secret with this name already exists.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/account/secrets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Secret identifier", "example": "2q9m7x4cavgd" } ], "get": { "operationId": "getSecret", "x-runpod-scope": "secrets:read", "summary": "Get a secret", "x-mint": { "metadata": { "description": "Retrieve a Runpod account secret's metadata by ID. The secret value is write-only and is never returned." } }, "description": "Returns a single secret's metadata by ID. The value is write-only and never returned.", "tags": [ "Account" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Secret" }, "examples": { "secret": { "summary": "Successful response", "value": { "id": "2q9m7x4cavgd", "name": "hf-token", "description": "Hugging Face read token", "createdAt": "2026-08-01T12:00:00Z", "valueLastUpdatedAt": "2026-09-01T08:30:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateSecret", "x-runpod-scope": "secrets:write", "summary": "Update a secret", "x-mint": { "metadata": { "description": "Update a Runpod account secret's description or rotate its value. The new value takes effect the next time a referencing Pod or worker boots." } }, "description": "Rotates a secret's value and/or updates its description. Only the\nprovided fields are changed and at least one field is required; the\n`name` is immutable.\n\nPods and workers receive the new value at their next boot — running\ninstances keep the value they were started with.\n\nWhen both fields are sent, the value is applied first, then the\ndescription. The two updates are not atomic: if the description\nupdate fails after the value was rotated, the response is an error\nbut the new value has already taken effect. Send the fields in\nseparate requests when that partial outcome matters.\n", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSecretRequest" }, "examples": { "rotateSecret": { "summary": "Rotate the value", "value": { "value": "hf_********************************" } }, "updateDescription": { "summary": "Update the description", "value": { "description": "Rotated HF token" } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Secret" }, "examples": { "secret": { "summary": "Successful response after rotation", "value": { "id": "2q9m7x4cavgd", "name": "hf-token", "description": "Rotated HF token", "createdAt": "2026-08-01T12:00:00Z", "valueLastUpdatedAt": "2026-09-10T17:40:12Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteSecret", "x-runpod-scope": "secrets:write", "summary": "Delete a secret", "x-mint": { "metadata": { "description": "Delete a Runpod account secret so Pods, Serverless endpoints, and templates can no longer resolve it from environment variables." } }, "description": "Permanently deletes a secret. Environment variables referencing the\ndeleted secret's name will no longer resolve to a value.\n", "tags": [ "Account" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/signup/authentication-attempts": { "post": { "operationId": "createAuthenticationAttempt", "security": [], "x-mint": { "metadata": { "description": "Email a verification code to sign in or create a Runpod account without an API key." } }, "summary": "Start an authentication attempt", "description": "Emails a verification code to sign in to an existing account or create a new one, without an API key. The response is the same whether or not an account exists for the email.", "tags": [ "Signup" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Use an unpredictable unique key, such as a UUID, for each new attempt. Retrying with the same key and body returns the same attempt without sending another email. For the same email, the same key with a different body is a `422`.", "example": "0f8c2d4e-6a1b-4c3d-9e7f-1a2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAuthenticationAttemptRequest" } } } }, "responses": { "201": { "description": "Created. A verification code was emailed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationAttempt" } } } }, "400": { "description": "The request is malformed or its body could not be read.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The incoming request body exceeds 4096 bytes (4 KiB).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/signup/authentication-attempts/{id}/verify": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "The `attemptId` returned when the attempt started." } ], "post": { "operationId": "verifyAuthenticationAttempt", "security": [], "x-mint": { "metadata": { "description": "Exchange an emailed verification code for a new Runpod API key." } }, "summary": "Verify an authentication attempt", "description": "Exchanges the emailed code and the `codeVerifier` whose hash started the attempt for a new API key, visible and revocable in the console. A wrong code is a `422`, and five wrong codes lock the attempt.", "tags": [ "Signup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyAuthenticationAttemptRequest" } } } }, "responses": { "200": { "description": "OK. The attempt is consumed and the key is issued.", "headers": { "Cache-Control": { "required": true, "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationAttemptResult" } } } }, "403": { "description": "The account requires SSO or MFA, or belongs to an organization. Sign in through the console instead.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No usable attempt matches this id and `codeVerifier`. It does not exist, expired, already issued a key, or locked after five wrong codes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "The request is malformed or its body could not be read.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The incoming request body exceeds 4096 bytes (4 KiB).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/signup/authentication-attempts/{id}/resend": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "The `attemptId` returned when the attempt started." } ], "post": { "operationId": "resendAuthenticationAttempt", "security": [], "x-mint": { "metadata": { "description": "Email a new verification code for a pending authentication attempt." } }, "summary": "Resend an authentication attempt's code", "description": "Emails a new verification code and invalidates the previous one. The attempt's `expiresAt` and wrong-code count carry over. Resending before `resendAfter` is a `429` with `Retry-After`.", "tags": [ "Signup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendAuthenticationAttemptRequest" } } } }, "responses": { "200": { "description": "OK. A new code was emailed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationAttempt" } } } }, "404": { "description": "No usable attempt matches this id and `codeVerifier`. It does not exist, expired, already issued a key, or locked after five wrong codes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "The request is malformed or its body could not be read.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The incoming request body exceeds 4096 bytes (4 KiB).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/pods": { "get": { "operationId": "listPods", "x-runpod-scope": "pods:read", "summary": "List pods", "x-mint": { "metadata": { "description": "List Pods owned by the authenticated Runpod user, with an option to include member Pods that belong to Runpod Clusters." } }, "description": "Returns pods owned by the authenticated user. Cluster member\npods are excluded by default; set `includeClusterPods=true` to include\nthem (each carries a non-null `cluster` membership block).\n\nResults are cursor-paginated newest-first; an omitted `limit`\ndefaults to 1000. The cluster-member exclusion is applied before the\npage is cut, so a page holds `limit` pods whenever that many remain.\nFollow `pagination.nextCursor` until `hasNextPage` is false.\n", "tags": [ "Pods" ], "parameters": [ { "name": "includeClusterPods", "in": "query", "required": false, "description": "Include cluster member pods in the result. Defaults to false.", "schema": { "type": "boolean", "default": false }, "example": false }, { "$ref": "#/components/parameters/ResourceFilters" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPodsResponse" }, "examples": { "pods": { "summary": "Successful response", "value": { "pods": [ { "id": "7h9k2m4n6p", "name": "pytorch-training", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "ports": [ "8888/http", "22/tcp" ], "env": { "MODEL_NAME": "llama-3" }, "registry": null, "status": "RUNNING", "actions": [ "stop", "restart", "terminate" ], "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "gpu": { "id": "NVIDIA GeForce RTX 4090", "count": 1, "vcpuCount": 16, "memory": 64 }, "cloud": "SECURE", "dataCenterId": "US-KS-2", "cudaVersion": "12.8", "ssh": { "proxy": { "host": "ssh.runpod.io", "port": 22, "username": "7h9k2m4n6p-64411eb2", "command": "ssh 7h9k2m4n6p-64411eb2@ssh.runpod.io" }, "direct": null }, "template": "9x4m2p7v", "cost": 0.44, "locked": false, "globalNetworking": { "enabled": false }, "runtime": null, "createdAt": "2026-06-01T12:00:00Z", "startedAt": "2026-06-01T12:02:00Z" } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createPod", "x-runpod-scope": "pods:write", "summary": "Create a pod", "x-mint": { "metadata": { "description": "Create a Runpod Pod with GPU or CPU compute, container or template settings, storage, networking, and deployment constraints." } }, "description": "Creates a new pod. `name` is always required; supply exactly one of\n`gpu` or `cpu` to select compute (a GPU or a CPU pod). Container\nsettings come from the body, from a template referenced by\n`templateId` (body fields override the template's), or both; `image`\nis required unless `templateId` is set. See `CreatePodRequest` for\nthe full body.\n\nReturns `201` with the created pod. Provisioning is asynchronous: the\npod starts in `PROVISIONING`, transitions through `STARTING`, and\nreaches `RUNNING` once its container is healthy. Poll `getPod` (or\nwatch the pod's `status`) to observe readiness rather than assuming\nthe pod is running when this call returns.\n\n## Checking what you can deploy\n\nThis endpoint places one specific GPU type. It does not search for\ncapacity, and it does not fall back to a different GPU. To find out\nwhat is deployable before you call it, read the catalog:\n\n- [List GPU types](https://docs.runpod.io/api-reference-v2/catalog/list-gpu-types)\n — GPU types with pricing, per-cloud ceilings, and, with\n `include=AVAILABILITY&product=POD`, current pod stock.\n- [List data centers](https://docs.runpod.io/api-reference-v2/catalog/list-data-centers)\n — locations, with `include=GPU_AVAILABILITY` for stock per data\n center.\n\nBoth accept filters that combine, so you can narrow by location and by\ncompute in one request — for example\n`GET /v2/catalog/datacenters?regions=EUROPE&include=GPU_AVAILABILITY`\nreturns only European data centers, each carrying the GPU types\ncurrently available there.\n\n## Deploying under region and GPU constraints\n\nIf you need a particular GPU in a particular geography, the working\npattern is read-then-create: narrow the catalog to an acceptable\n(data center, GPU) set, then call this endpoint once per candidate in\nyour order of preference until one returns `201`. The runnable sample\nalongside this operation does exactly that.\n\nAvailability can change between the catalog read and the create call,\nso treat the catalog as a way to order your candidates, not as a\nreservation — a create can still fail for capacity on a GPU the\ncatalog just reported as available.\n\nWhich failures are worth retrying:\n\n| Status | Meaning | Do |\n| --- | --- | --- |\n| `422` | The body does not match the contract. `errors` lists each violation. | Fix the request. Never retry. |\n| `400` | The body matches the contract but was rejected — either it breaks a cross-field rule, or this GPU and data center combination could not be placed. | Try your next candidate. |\n| `402` | Insufficient balance. | Stop; no candidate will succeed. |\n| `403` | Your account cannot access the requested pool. | Skip this candidate, keep going. |\n| `429` | Rate limited. | Back off using `Retry-After`, then resume. |\n| `5xx` | Transient server failure. | Retry the same candidate with backoff. |\n\nRequests larger than 102400 bytes receive `413` after authentication\nand rate limiting, before deployment processing. Reduce the serialized\nJSON request body and retry.\n\nThis limit also applies to the deployment request built from your input\nand any referenced template. A small request can therefore receive `413`\nif inherited template settings make the combined request too large.\nReduce environment variables or command values in your request or template\nand retry.\n\n`400` covers both \"your request breaks a rule\" and \"no capacity\",\nbecause capacity exhaustion currently carries no machine-readable code\nof its own — only a human-readable `detail`. A rule violation is\ndeterministic, so it fails identically on every candidate: if *every*\ncandidate returns `400`, read the last `detail` as a problem with the\nrequest rather than as absent capacity.\n", "tags": [ "Pods" ], "x-codeSamples": [ { "lang": "Python", "label": "Region-constrained deploy loop", "source": "import os\nimport time\n\nimport requests\n\nAPI = \"https://api.runpod.io\"\nSESSION = requests.Session()\nSESSION.headers[\"Authorization\"] = f\"Bearer {os.environ['RUNPOD_API_KEY']}\"\n\n# Most preferred GPU first. The loop stops at the first one that places.\nGPU_PREFERENCE = [\n \"NVIDIA GeForce RTX 4090\",\n \"NVIDIA GeForce RTX 5090\",\n \"NVIDIA H100 PCIe\",\n]\nUSABLE = {\"LOW\", \"MEDIUM\", \"HIGH\"} # anything but NONE\n\n\ndef candidates(region):\n \"\"\"(gpu_id, datacenter_id) pairs that the catalog reports as deployable,\n ordered by GPU_PREFERENCE then by descending stock.\"\"\"\n response = SESSION.get(\n f\"{API}/v2/catalog/datacenters\",\n params={\"regions\": region, \"include\": \"GPU_AVAILABILITY\"},\n timeout=30,\n )\n response.raise_for_status()\n\n rank = {\"HIGH\": 0, \"MEDIUM\": 1, \"LOW\": 2}\n found = []\n for datacenter in response.json()[\"dataCenters\"]:\n for gpu in datacenter.get(\"gpuAvailability\", []):\n if gpu[\"id\"] in GPU_PREFERENCE and gpu[\"availability\"] in USABLE:\n found.append((gpu[\"id\"], datacenter[\"id\"], gpu[\"availability\"]))\n\n found.sort(key=lambda c: (GPU_PREFERENCE.index(c[0]), rank[c[2]]))\n return [(gpu_id, dc_id) for gpu_id, dc_id, _ in found]\n\n\ndef create(gpu_id, datacenter_id):\n return SESSION.post(\n f\"{API}/v2/pods\",\n json={\n \"name\": \"inference-worker\",\n \"image\": \"runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404\",\n \"gpu\": {\"id\": gpu_id, \"count\": 1},\n \"dataCenterIds\": [datacenter_id],\n \"disk\": 50,\n },\n timeout=60,\n )\n\n\ndef create_with_backoff(gpu_id, datacenter_id, attempts=5):\n \"\"\"Rate limits and 5xx are not the candidate's fault, so they are\n retried in place rather than moving to the next GPU.\"\"\"\n for attempt in range(attempts):\n response = create(gpu_id, datacenter_id)\n if response.status_code == 429:\n # Retry-After is integer seconds on this API.\n time.sleep(int(response.headers.get(\"Retry-After\", 5)))\n continue\n if response.status_code >= 500:\n time.sleep(2**attempt)\n continue\n return response\n raise RuntimeError(f\"{attempts} transient failures for {gpu_id}; service unhealthy\")\n\n\ndef deploy(region=\"EUROPE\"):\n last_detail = None\n\n for gpu_id, datacenter_id in candidates(region):\n response = create_with_backoff(gpu_id, datacenter_id)\n\n if response.status_code == 201:\n return response.json()\n\n problem = response.json()\n last_detail = problem.get(\"detail\")\n\n if response.status_code == 422:\n # Contract violation — identical on every candidate.\n raise SystemExit(f\"Bad request: {problem.get('errors', last_detail)}\")\n if response.status_code == 402:\n raise SystemExit(f\"Cannot deploy: {last_detail}\")\n if response.status_code in (400, 403):\n # 403: no access to this pool. 400: rule violation, or this\n # GPU/data center could not be placed. Either way, move on.\n continue\n\n response.raise_for_status()\n\n # Every candidate was refused. A rule violation fails the same way on\n # all of them, so the last detail is the useful signal here.\n raise SystemExit(f\"No candidate placed in {region}. Last error: {last_detail}\")\n\n\nif __name__ == \"__main__\":\n pod = deploy()\n print(f\"{pod['id']} placed in {pod['dataCenterId']} on {pod['gpu']['id']}\")\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePodRequest" }, "examples": { "gpuPod": { "summary": "GPU pod", "value": { "name": "pytorch-training", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "gpu": { "id": "NVIDIA GeForce RTX 4090", "count": 1, "minRamPerGpu": 32, "minVcpuCountPerGpu": 8 }, "disk": 50 } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pod" }, "examples": { "pod": { "summary": "Successful response", "value": { "id": "7h9k2m4n6p", "name": "pytorch-training", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "ports": [ "8888/http", "22/tcp" ], "env": { "MODEL_NAME": "llama-3" }, "registry": null, "status": "PROVISIONING", "actions": [ "start", "terminate" ], "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "gpu": { "id": "NVIDIA GeForce RTX 4090", "count": 1, "vcpuCount": 16, "memory": 64 }, "cloud": "SECURE", "dataCenterId": "US-KS-2", "cudaVersion": "12.8", "ssh": { "proxy": { "host": "ssh.runpod.io", "port": 22, "username": "7h9k2m4n6p-64411eb2", "command": "ssh 7h9k2m4n6p-64411eb2@ssh.runpod.io" }, "direct": null }, "template": "9x4m2p7v", "cost": 0.44, "locked": false, "globalNetworking": { "enabled": false }, "runtime": null, "createdAt": "2026-06-01T12:00:00Z", "startedAt": null } } } } } }, "202": { "headers": { "Location": { "description": "Where to read the queued pod (`GET /v2/queued-pods/{id}`).", "schema": { "type": "string" }, "example": "/v2/queued-pods/clz1x9k4a0000qw3h8s7d2f1g" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Queued. The request carried `queue` and the GPU had no capacity\n(or `queue.startsAt` is in the future), so no pod exists yet. The\nbody is the queued pod; poll `Location` until its `status` leaves\n`QUEUED`, or cancel it with `DELETE /v2/queued-pods/{id}`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedPod" }, "examples": { "queuedPod": { "summary": "Queued for capacity", "value": { "id": "clz1x9k4a0000qw3h8s7d2f1g", "status": "QUEUED", "podId": null, "failureReason": null, "name": "pytorch-training", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "templateId": null, "gpu": { "id": "NVIDIA GeForce RTX 4090", "count": 1 }, "cloud": "SECURE", "dataCenterIds": [ "EU-RO-1" ], "queue": { "startsAt": null, "expiresAt": "2026-07-01T12:00:00Z", "allowedHours": null, "notifyEmail": null }, "createdAt": "2026-06-01T12:00:00Z", "resolvedAt": null } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "The request carried `queue`, but the account already has as many\nqueued pods as its plan allows. Cancel a queued pod or upgrade the\nplan.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The incoming request body, or the request it expands into, exceeds the 102400 byte limit or is rejected as too large.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/pods/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pod identifier", "example": "pod_abc123" } ], "get": { "operationId": "getPod", "x-runpod-scope": "pods:read", "summary": "Get a pod", "x-mint": { "metadata": { "description": "Retrieve a Runpod Pod by ID with its compute, container, storage, networking, lifecycle status, and connection details." } }, "description": "Returns a single pod by ID.", "tags": [ "Pods" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pod" }, "examples": { "pod": { "summary": "Successful response", "value": { "id": "7h9k2m4n6p", "name": "pytorch-training", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "ports": [ "8888/http", "22/tcp" ], "env": { "MODEL_NAME": "llama-3" }, "registry": null, "status": "RUNNING", "actions": [ "stop", "restart", "terminate" ], "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "gpu": { "id": "NVIDIA GeForce RTX 4090", "count": 1, "vcpuCount": 16, "memory": 64 }, "cloud": "SECURE", "dataCenterId": "US-KS-2", "cudaVersion": "12.8", "ssh": { "proxy": { "host": "ssh.runpod.io", "port": 22, "username": "7h9k2m4n6p-64411eb2", "command": "ssh 7h9k2m4n6p-64411eb2@ssh.runpod.io" }, "direct": { "host": "195.26.233.3", "port": 34446, "username": "root", "command": "ssh root@195.26.233.3 -p 34446" } }, "template": "9x4m2p7v", "cost": 0.44, "locked": false, "globalNetworking": { "enabled": false }, "runtime": { "uptime": 3600, "ports": [ { "private": 22, "public": 34446, "type": "tcp", "ip": "195.26.233.3" } ] }, "createdAt": "2026-06-01T12:00:00Z", "startedAt": "2026-06-01T12:02:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updatePod", "x-runpod-scope": "pods:write", "summary": "Update a pod", "x-mint": { "metadata": { "description": "Update selected settings on an existing Runpod Pod while preserving omitted fields, with guidance on mutable fields and restart behavior." } }, "description": "Partially updates a pod's configuration. This is a PATCH: only the\nfields present in the body are changed, and omitted fields are left\nuntouched. Use empty values only when you explicitly mean to clear a\nfield (for example, set `registry` to `null` or set `ports` to `[]`).\nSee `UpdatePodRequest` for the full body.\n\nMutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`,\n`registry`, `mounts`, `locked`, and `globalNetworking`. Some changes\napply immediately while others (e.g. `globalNetworking`) take effect\non the pod's next start/restart, as noted on the individual fields.\n\nVolumes can be mounted, moved, or unmounted after creation through\n`mounts`, one entry per volume; see `UpdatePodMounts` for the rules.\n\nPods that belong to a Cluster cannot be updated here — manage them\nthrough `/v2/clusters/{id}`.\n\nReturns `200` with the full updated pod.\n", "tags": [ "Pods" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePodRequest" }, "examples": { "renamePod": { "summary": "Rename pod", "value": { "name": "renamed-training-pod" } }, "mountNetworkVolume": { "summary": "Mount a network volume", "value": { "mounts": { "network": [ { "volumeId": "vol_abc", "path": "/datasets" } ] } } }, "swapNetworkVolume": { "summary": "Swap one network volume for another", "value": { "mounts": { "network": [ { "volumeId": "vol_xyz", "remove": true }, { "volumeId": "vol_abc", "path": "/workspace" } ] } } }, "unmountNetworkVolume": { "summary": "Unmount a network volume", "value": { "mounts": { "network": [ { "volumeId": "vol_xyz", "remove": true } ] } } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pod" }, "examples": { "pod": { "summary": "Successful response", "value": { "id": "7h9k2m4n6p", "name": "renamed-training-pod", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "ports": [ "8888/http", "22/tcp" ], "env": { "MODEL_NAME": "llama-3" }, "registry": null, "status": "RUNNING", "actions": [ "stop", "restart", "terminate" ], "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "gpu": { "id": "NVIDIA GeForce RTX 4090", "count": 1, "vcpuCount": 16, "memory": 64 }, "cloud": "SECURE", "dataCenterId": "US-KS-2", "cudaVersion": "12.8", "ssh": { "proxy": { "host": "ssh.runpod.io", "port": 22, "username": "7h9k2m4n6p-64411eb2", "command": "ssh 7h9k2m4n6p-64411eb2@ssh.runpod.io" }, "direct": { "host": "195.26.233.3", "port": 34446, "username": "root", "command": "ssh root@195.26.233.3 -p 34446" } }, "template": "9x4m2p7v", "cost": 0.44, "locked": false, "globalNetworking": { "enabled": false }, "runtime": { "uptime": 3600, "ports": [ { "private": 22, "public": 34446, "type": "tcp", "ip": "195.26.233.3" } ] }, "createdAt": "2026-06-01T12:00:00Z", "startedAt": "2026-06-01T12:02:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "409": { "description": "Pod belongs to a cluster and cannot be modified via the pod endpoints.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deletePod", "x-runpod-scope": "pods:write", "summary": "Terminate a pod", "x-mint": { "metadata": { "description": "Permanently terminate a Runpod Pod, release its compute, and understand what happens to persistent mounts, network volumes, and Cluster members." } }, "description": "Permanently terminates and deletes a pod. This is irreversible:\ncompute is released, any `mounts.persistent` host-local storage is\ndestroyed with it (a `mounts.network` volume is only detached — the\nvolume itself is not deleted), and the pod no longer appears in\n`listPods`.\n\nPods that belong to a Cluster cannot be terminated here — delete the\ncluster via `DELETE /v2/clusters/{id}`.\n", "tags": [ "Pods" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Pod belongs to a cluster and cannot be terminated via the pod endpoints.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/pods/{id}/logs": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pod identifier", "example": "pod_abc123" } ], "get": { "operationId": "getPodLogs", "x-runpod-scope": "pods:read", "summary": "Stream pod logs", "x-mint": { "metadata": { "description": "Stream a Runpod Pod's container and system logs in real time as Server-Sent Events, with resumable reconnects via Last-Event-ID." } }, "description": "Streams pod logs as Server-Sent Events. The `source` query parameter\nselects which log source to include.\n\nThe SSE `data` payload shape is:\n`{ \"source\": \"container\", \"line\": \"...\", \"ts\": \"...\" }`.\nLog-event `id` values are the event `ts` timestamp so\nbrowser/EventSource reconnects can resume with `Last-Event-ID`.\n", "tags": [ "Pods" ], "parameters": [ { "$ref": "#/components/parameters/LogSourceParam" }, { "$ref": "#/components/parameters/LogTail" }, { "$ref": "#/components/parameters/LogSince" }, { "$ref": "#/components/parameters/LogLastEventID" } ], "responses": { "200": { "description": "Pod log event stream", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Cache-Control": { "schema": { "type": "string" }, "description": "Always `no-cache` for SSE responses." }, "Connection": { "schema": { "type": "string" }, "description": "Always `keep-alive` to hold the SSE stream open." }, "X-Accel-Buffering": { "schema": { "type": "string" }, "description": "Always `no` to disable proxy buffering of the SSE stream." } }, "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream. Each event includes an `id:` line and a JSON `data:` payload with `source`, `line`, and `ts` fields." }, "examples": { "logLine": { "summary": "Successful response", "value": "id: 2026-06-01T12:02:03Z/000000000001\ndata: {\"ts\":\"2026-06-01T12:02:03Z\",\"source\":\"container\",\"line\":\"Model loaded.\"}\n" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/pods/{id}/action": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "pod_abc123" } ], "post": { "operationId": "podAction", "x-runpod-scope": "pods:write", "summary": "Trigger a pod state transition", "x-mint": { "metadata": { "description": "Start, stop, or restart a Runpod Pod by sending a supported state transition action and retrieving the Pod's updated lifecycle state." } }, "description": "Triggers a state transition on a pod. Send a JSON body with a single\n`action` field, e.g. `{ \"action\": \"stop\" }`.\n\nValid actions:\n- `start` — boot a stopped pod (`EXITED` or `ERROR`) back toward\n `RUNNING`.\n- `stop` — stop a running or provisioning pod, releasing GPU/CPU\n compute while keeping its disk. The pod moves to `EXITED`.\n- `restart` — restart a `RUNNING` pod's container in place.\n- `terminate` — permanently delete the pod and release its resources\n (equivalent to `deletePod`).\n\nWhich actions are valid depends on the pod's current status, and the\ncurrently permitted set is published in the pod's `actions` field:\n`RUNNING` allows `stop`/`restart`/`terminate`; `EXITED` and `ERROR`\nallow `start`/`terminate`; `PROVISIONING` and `STARTING` allow\n`stop`/`terminate`.\n\n`start`, `stop`, and `restart` return `200` with the updated pod.\n`terminate` returns `204` with no body. Requesting an action that is\nnot valid for the pod's current status returns `409`.\n", "tags": [ "Pods" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodActionRequest" }, "examples": { "startPod": { "summary": "Start pod", "value": { "action": "start" } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Action applied — returns updated pod", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pod" }, "examples": { "pod": { "summary": "Successful response", "value": { "id": "7h9k2m4n6p", "name": "pytorch-training", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "ports": [ "8888/http", "22/tcp" ], "env": { "MODEL_NAME": "llama-3" }, "registry": null, "status": "RUNNING", "actions": [ "stop", "restart", "terminate" ], "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "gpu": { "id": "NVIDIA GeForce RTX 4090", "count": 1, "vcpuCount": 16, "memory": 64 }, "cloud": "SECURE", "dataCenterId": "US-KS-2", "cudaVersion": "12.8", "ssh": { "proxy": { "host": "ssh.runpod.io", "port": 22, "username": "7h9k2m4n6p-64411eb2", "command": "ssh 7h9k2m4n6p-64411eb2@ssh.runpod.io" }, "direct": { "host": "195.26.233.3", "port": 34446, "username": "root", "command": "ssh root@195.26.233.3 -p 34446" } }, "template": "9x4m2p7v", "cost": 0.44, "locked": false, "globalNetworking": { "enabled": false }, "runtime": { "uptime": 3600, "ports": [ { "private": 22, "public": 34446, "type": "tcp", "ip": "195.26.233.3" } ] }, "createdAt": "2026-06-01T12:00:00Z", "startedAt": "2026-06-01T12:02:00Z" } } } } } }, "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Only returned when `action=terminate`; response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Action not valid for current pod status", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/pods/{id}/exec": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pod identifier", "example": "pod_abc123" } ], "post": { "operationId": "execPod", "x-runpod-scope": "pods:write", "summary": "Run a command in a pod", "x-mint": { "metadata": { "description": "Run one command inside a running Runpod Pod's container and get its stdout, stderr, and exit code back, with no SSH setup." } }, "description": "Runs one command inside the pod's container and returns its stdout,\nstderr and exit code once it finishes. No SSH key, public IP or exposed\nport is needed, and it works with any image.\n\n`command` is an argv array, run directly and never through a shell. For\npipes, redirects or globbing pass `[\"sh\", \"-c\", \"...\"]`.\n\nA command that exits non-zero is a result, not an error: the call\nanswers `200` with `exitCode` set. A command still running after\n`timeoutSeconds` (1-25, default 20) answers `200` with\n`timedOut: true` and a null `exitCode`. `timedOut` means the call\nstopped waiting, not that the command was stopped: it may keep\nrunning in the container.\n\n`stdout` and `stderr` are each capped at 1 MiB. Output past the cap is\ncut and `truncated` is `true`.\n\nThe pod must be running with its container up, otherwise this answers\n`409`; while the container is still starting, the `409` carries\n`Retry-After`. A pod whose machine has not been updated for exec yet\nanswers `503` with `Retry-After`.\n\nA caller whose team or organization role lacks the Terminal permission\ngets `403`.\n", "tags": [ "Pods" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodExecRequest" }, "examples": { "gpuQuery": { "summary": "Query the GPU", "value": { "command": [ "nvidia-smi", "--query-gpu=name,memory.used", "--format=csv" ], "timeoutSeconds": 10 } }, "failingInstall": { "summary": "Shell command in a working directory", "value": { "command": [ "sh", "-c", "pip install -q nosuchpackage" ], "cwd": "/workspace" } }, "timeout": { "summary": "Command that outlives its timeout", "value": { "command": [ "sleep", "120" ], "timeoutSeconds": 5 } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The command finished or the call stopped waiting for it. A non-zero `exitCode` is a result, not an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodExecResult" }, "examples": { "gpuQuery": { "summary": "Command succeeded", "value": { "stdout": "name, memory.used [MiB]\nNVIDIA H100 80GB HBM3, 0 MiB\n", "stderr": "", "exitCode": 0, "timedOut": false, "truncated": false, "durationMs": 412 } }, "failingInstall": { "summary": "Command exited non-zero", "value": { "stdout": "", "stderr": "ERROR: No matching distribution found for nosuchpackage\n", "exitCode": 1, "timedOut": false, "truncated": false, "durationMs": 2310 } }, "timeout": { "summary": "Call stopped waiting", "value": { "stdout": "", "stderr": "", "exitCode": null, "timedOut": true, "truncated": false, "durationMs": 5003 } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Sent only while the pod's container is starting.", "schema": { "type": "integer" }, "example": 5 }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The pod is not running, or its container has not started yet. A\ncontainer that is starting answers with `Retry-After`.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "502": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The call did not complete. When the pod could not be looked up, or\nits machine or the exec service could not be reached, the command\ndid not start: retry the call. When the command was sent but no\nusable answer came back, it may still be running: check before you\nretry. When the result could not be read, the command ran.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" }, "example": 30 }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Command execution is not available for this pod right now: its\nmachine has not been updated for exec, execution is busy, or it is\ntemporarily unavailable. The pod itself is unaffected; retry after\n`Retry-After`.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The pod's machine, or the exec service in front of it, did not\nanswer in time. The command may still be running: check before you\nretry.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/queued-pods": { "get": { "operationId": "listQueuedPods", "x-runpod-scope": "pods:read", "summary": "List queued pods", "x-mint": { "metadata": { "description": "List the Runpod Pods queued for deploy-when-available, with each one's status, the pod it created, and why any failed." } }, "description": "Returns the caller's queued pods, cursor-paginated newest-first; an\nomitted `limit` defaults to 1000. Every queued pod is listed whatever\nits `status`, so the outcome of a queued create can be read after the\nfact. Follow `pagination.nextCursor` until `hasNextPage` is false.\n", "tags": [ "Pods" ], "parameters": [ { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListQueuedPodsResponse" }, "examples": { "queuedPods": { "summary": "Successful response", "value": { "queuedPods": [ { "id": "clz1x9k4a0000qw3h8s7d2f1g", "status": "DEPLOYED", "podId": "7h9k2m4n6p", "failureReason": null, "name": "pytorch-training", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "templateId": null, "gpu": { "id": "NVIDIA GeForce RTX 4090", "count": 1 }, "cloud": "SECURE", "dataCenterIds": [ "EU-RO-1" ], "queue": { "startsAt": null, "expiresAt": "2026-07-01T12:00:00Z", "allowedHours": null, "notifyEmail": null }, "createdAt": "2026-06-01T12:00:00Z", "resolvedAt": "2026-06-01T13:05:00Z" } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/queued-pods/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Queued pod identifier", "example": "clz1x9k4a0000qw3h8s7d2f1g" } ], "get": { "operationId": "getQueuedPod", "x-runpod-scope": "pods:read", "summary": "Get a queued pod", "x-mint": { "metadata": { "description": "Retrieve a queued Runpod Pod by ID to see whether it is still waiting for capacity, which pod it created, or why it failed." } }, "description": "Returns a single queued pod by ID. Poll it after a `202` from\n`createPod`: `status` moves from `QUEUED` to `DEPLOYED` (with\n`podId`), `FAILED` (with `failureReason`), `EXPIRED`, or `CANCELLED`.\n", "tags": [ "Pods" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedPod" }, "examples": { "queuedPod": { "summary": "Still waiting", "value": { "id": "clz1x9k4a0000qw3h8s7d2f1g", "status": "QUEUED", "podId": null, "failureReason": null, "name": "pytorch-training", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "templateId": null, "gpu": { "id": "NVIDIA GeForce RTX 4090", "count": 1 }, "cloud": "SECURE", "dataCenterIds": [ "EU-RO-1" ], "queue": { "startsAt": null, "expiresAt": "2026-07-01T12:00:00Z", "allowedHours": { "monday": [ 9, 10, 11, 12, 13, 14, 15, 16 ] }, "notifyEmail": null }, "createdAt": "2026-06-01T12:00:00Z", "resolvedAt": null } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteQueuedPod", "x-runpod-scope": "pods:write", "summary": "Cancel a queued pod", "x-mint": { "metadata": { "description": "Cancel a queued Runpod Pod so it is no longer deployed when capacity opens." } }, "description": "Cancels a queued pod: it leaves the queue and is never deployed. A\npod it already created is untouched; terminate that with\n`DELETE /v2/pods/{id}`. Cancelling a queued pod that already\ndeployed, failed or expired changes nothing and still answers `204`.\n", "tags": [ "Pods" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Cancelled. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/clusters": { "get": { "operationId": "listClusters", "x-runpod-scope": "clusters:read", "summary": "List clusters", "x-mint": { "metadata": { "description": "List all Runpod Clusters owned by the authenticated user, including each Cluster's configuration, status, and aggregate Pod counts." } }, "description": "Returns clusters owned by the authenticated user, cursor-paginated\nnewest-first; an omitted `limit` defaults to 1000. Follow\n`pagination.nextCursor` until `hasNextPage` is false.\n", "tags": [ "Clusters" ], "parameters": [ { "$ref": "#/components/parameters/ResourceFilters" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClustersResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createCluster", "x-runpod-scope": "clusters:write", "summary": "Create a cluster", "x-mint": { "metadata": { "description": "Create a multi-node Runpod Cluster with a consistent compute shape and container configuration across every member Pod." } }, "description": "Creates a multi-node cluster. `compute` sets the homogeneous\npod shape; the container configuration applies to every pod and can be spread\nfrom a template response.\n", "tags": [ "Clusters" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClusterRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cluster" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/clusters/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cluster identifier", "example": "cluster_abc123" } ], "get": { "operationId": "getCluster", "x-runpod-scope": "clusters:read", "summary": "Get a cluster", "x-mint": { "metadata": { "description": "Retrieve a Runpod Cluster by ID with its configuration, status, and an aggregate summary of member Pods by status." } }, "description": "Returns a single cluster by ID. The pods field is an aggregate summary (total + count by status); fetch the member pods themselves from /v2/clusters/{id}/pods.", "tags": [ "Clusters" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cluster" } } } }, "404": { "description": "Cluster not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateCluster", "x-runpod-scope": "clusters:write", "summary": "Rename a cluster", "x-mint": { "metadata": { "description": "Rename a Runpod Cluster. Compute shape, type, and container configuration are fixed at creation and cannot be changed." } }, "description": "Renames a cluster. This endpoint only changes the cluster\nname — compute shape, type, and container configuration are fixed at\ncreation and cannot be updated.\n", "tags": [ "Clusters" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClusterRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cluster" } } } }, "404": { "description": "Cluster not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteCluster", "x-runpod-scope": "clusters:write", "summary": "Delete a cluster", "x-mint": { "metadata": { "description": "Permanently delete a Runpod Cluster and terminate all of its member Pods, with the response confirming the deleted Cluster." } }, "description": "Permanently deletes a cluster and terminates all of its member pods.", "tags": [ "Clusters" ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Cluster not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/clusters/{id}/pods": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cluster identifier", "example": "cluster_abc123" } ], "get": { "operationId": "listClusterPods", "x-runpod-scope": "clusters:read", "summary": "List a cluster's pods", "x-mint": { "metadata": { "description": "List every Pod in a Runpod Cluster with each member's complete configuration and status, beyond the aggregate counts in the Cluster summary." } }, "description": "Returns the full member pods of a cluster. The cluster summary (`GET /v2/clusters/{id}`) carries only aggregate pod counts; this endpoint returns each member as a complete Pod object.", "tags": [ "Clusters" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodList" } } } }, "404": { "description": "Cluster not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless": { "get": { "operationId": "listEndpoints", "x-runpod-scope": "serverless:read", "summary": "List serverless endpoints", "x-mint": { "metadata": { "description": "List all Runpod Serverless endpoints owned by the authenticated user, including compute, worker, scaling, and deployment settings." } }, "description": "Returns serverless endpoints owned by the authenticated user,\ncursor-paginated newest-first; an omitted `limit` defaults to 1000.\nFollow `pagination.nextCursor` until `hasNextPage` is false.\n", "tags": [ "Serverless" ], "parameters": [ { "$ref": "#/components/parameters/ResourceFilters" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointsResponse" }, "examples": { "endpoints": { "summary": "Successful response", "value": { "endpoints": [ { "id": "4m7x2k9q", "name": "image-generator", "type": "QUEUE", "requestUrls": { "run": "https://api.runpod.ai/v2/4m7x2k9q/run", "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync", "status": "https://api.runpod.ai/v2/4m7x2k9q/status/{job_id}", "stream": "https://api.runpod.ai/v2/4m7x2k9q/stream/{job_id}", "cancel": "https://api.runpod.ai/v2/4m7x2k9q/cancel/{job_id}", "retry": "https://api.runpod.ai/v2/4m7x2k9q/retry/{job_id}", "purgeQueue": "https://api.runpod.ai/v2/4m7x2k9q/purge-queue", "health": "https://api.runpod.ai/v2/4m7x2k9q/health" }, "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 20, "ports": [ "8000/http" ], "env": { "MODEL_NAME": "sdxl" }, "registry": null, "gpu": { "pools": [ "ADA_24" ], "count": 1, "allowedCudaVersions": [], "minCudaVersion": null }, "workers": { "min": 0, "max": 5, "idleTimeout": 5, "initTimeout": null }, "scaling": { "type": "QUEUE_DELAY", "queueDelay": 4 }, "dataCenterIds": [ "US-KS-2" ], "networkVolumes": [ "2q9m7x4c" ], "mounts": { "network": [ { "volumeId": "2q9m7x4c" } ], "global": [] }, "timeout": 300000, "flashboot": "OFF", "createdAt": "2026-06-01T12:00:00Z" } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createEndpoint", "x-runpod-scope": "serverless:write", "summary": "Create a serverless endpoint", "x-mint": { "metadata": { "description": "Create a Runpod Serverless endpoint with GPU or CPU compute, container or template settings, worker limits, and scaling policies." } }, "description": "Creates a serverless endpoint. Callers specify exactly one of `gpu` or\n`cpu`; neither or both returns 400. Container settings come from the\nbody, from a serverless template referenced by `templateId` (body\nfields override the template's), or both; `image` is required unless\n`templateId` is set. See `CreateEndpointRequest` for the full body.\nAn image in a private Amazon ECR registry with no `registry`\ncredential must be covered by one of your ECR delegations (see\n`registry`); otherwise the create returns 400 here rather than\nworkers failing their image pull. A caller whose organization role\ncannot use ECR delegations gets 403.\n\nThe CUDA constraints live on `gpu` — `gpu.allowedCudaVersions` and\n`gpu.minCudaVersion` — so a CPU create cannot express them and the\nschema rejects the attempt with a 422. A non-empty set and a floor are\nmutually exclusive (400 if both are sent); an explicit empty set states\nno constraint and may accompany a floor.\n\nReturns `201` with the created endpoint. The endpoint can accept jobs\nimmediately, but starts with no active workers unless `workers.min`\nis greater than 0. Workers are provisioned on demand and autoscaled\nbetween `workers.min` and `workers.max` according to the `scaling`\npolicy, so the first request to an idle endpoint may incur cold-start\nlatency while a worker pulls its image and boots.\n\n## Checking what you can deploy\n\n`gpu.pools` takes serverless GPU **pool** IDs, not the GPU type IDs\nused for pods. `gpu.excludedTypes` takes the type IDs — it subtracts\nspecific cards from the pools you picked. Read both from the catalog\nbefore you create:\n\n- [List GPU types](https://docs.runpod.io/api-reference-v2/catalog/list-gpu-types)\n — the `pool` field carries the pool ID for each GPU type (`null`\n means that type is not in a serverless pool). Add\n `include=AVAILABILITY&product=SERVERLESS` for current serverless\n stock.\n- [List data centers](https://docs.runpod.io/api-reference-v2/catalog/list-data-centers)\n — locations to constrain with `dataCenterIds`, with\n `include=GPU_AVAILABILITY` for stock per data center.\n\nUnlike pod creation, you do not need to retry across GPUs yourself:\nlist every pool you are willing to run on and workers are placed on\nwhichever one has capacity. Listing more pools — and leaving\n`dataCenterIds` unset — gives the scheduler more room and reduces the\nchance of workers failing to start when a single pool is exhausted.\n\nIf your workload needs a specific card, pick the pool that holds it and\nexclude the rest of that pool with `gpu.excludedTypes`. Keep at least\none type in the selection — a selection that leaves none is\nrejected.\n", "tags": [ "Serverless" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEndpointRequest" }, "examples": { "serverlessEndpoint": { "summary": "Serverless GPU endpoint", "value": { "name": "image-generator", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "type": "QUEUE", "gpu": { "pools": [ "ADA_24" ], "count": 1 }, "workers": { "min": 0, "max": 5, "idleTimeout": 5 }, "scaling": { "type": "QUEUE_DELAY", "queueDelay": 4 }, "dataCenterIds": [ "US-KS-2" ], "timeout": 300000 } }, "cpuServerlessEndpoint": { "summary": "Serverless CPU endpoint with multiple configurations", "value": { "name": "cpu-inference", "image": "python:3.11-slim", "type": "QUEUE", "cpu": [ { "id": "cpu5c", "vcpuCount": 4 }, { "id": "cpu5g", "vcpuCount": 8 } ], "workers": { "min": 0, "max": 3, "idleTimeout": 10 }, "scaling": { "type": "QUEUE_DELAY", "queueDelay": 4 }, "timeout": 300000 } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" }, "examples": { "endpoint": { "summary": "Successful response", "value": { "id": "4m7x2k9q", "name": "image-generator", "type": "QUEUE", "requestUrls": { "run": "https://api.runpod.ai/v2/4m7x2k9q/run", "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync", "status": "https://api.runpod.ai/v2/4m7x2k9q/status/{job_id}", "stream": "https://api.runpod.ai/v2/4m7x2k9q/stream/{job_id}", "cancel": "https://api.runpod.ai/v2/4m7x2k9q/cancel/{job_id}", "retry": "https://api.runpod.ai/v2/4m7x2k9q/retry/{job_id}", "purgeQueue": "https://api.runpod.ai/v2/4m7x2k9q/purge-queue", "health": "https://api.runpod.ai/v2/4m7x2k9q/health" }, "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 20, "ports": [ "8000/http" ], "env": { "MODEL_NAME": "sdxl" }, "registry": null, "gpu": { "pools": [ "ADA_24" ], "count": 1, "allowedCudaVersions": [], "minCudaVersion": null }, "workers": { "min": 0, "max": 5, "idleTimeout": 5, "initTimeout": null }, "scaling": { "type": "QUEUE_DELAY", "queueDelay": 4 }, "dataCenterIds": [ "US-KS-2" ], "networkVolumes": [ "2q9m7x4c" ], "mounts": { "network": [ { "volumeId": "2q9m7x4c" } ], "global": [] }, "timeout": 300000, "flashboot": "OFF", "createdAt": "2026-06-01T12:00:00Z" } }, "cpuEndpoint": { "summary": "Successful response for a CPU endpoint", "value": { "id": "7c3v1n8p", "name": "cpu-inference", "type": "QUEUE", "requestUrls": { "run": "https://api.runpod.ai/v2/7c3v1n8p/run", "runSync": "https://api.runpod.ai/v2/7c3v1n8p/runsync", "status": "https://api.runpod.ai/v2/7c3v1n8p/status/{job_id}", "stream": "https://api.runpod.ai/v2/7c3v1n8p/stream/{job_id}", "cancel": "https://api.runpod.ai/v2/7c3v1n8p/cancel/{job_id}", "retry": "https://api.runpod.ai/v2/7c3v1n8p/retry/{job_id}", "purgeQueue": "https://api.runpod.ai/v2/7c3v1n8p/purge-queue", "health": "https://api.runpod.ai/v2/7c3v1n8p/health" }, "image": "python:3.11-slim", "args": "", "disk": 20, "ports": [], "env": {}, "registry": null, "cpu": [ { "id": "cpu5c", "vcpuCount": 4, "memory": 16 }, { "id": "cpu5g", "vcpuCount": 8, "memory": 16 } ], "workers": { "min": 0, "max": 3, "idleTimeout": 10, "initTimeout": null }, "scaling": { "type": "QUEUE_DELAY", "queueDelay": 4 }, "dataCenterIds": [], "networkVolumes": [], "mounts": { "network": [], "global": [] }, "timeout": 300000, "flashboot": "OFF", "createdAt": "2026-06-01T12:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serverless endpoint identifier", "example": "ep_abc123" } ], "get": { "operationId": "getEndpoint", "x-runpod-scope": "serverless:read", "summary": "Get a serverless endpoint", "x-mint": { "metadata": { "description": "Retrieve a Runpod Serverless endpoint by ID with its compute, worker, scaling, container, storage, and current status settings." } }, "description": "Returns a single serverless endpoint by ID.", "tags": [ "Serverless" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" }, "examples": { "endpoint": { "summary": "Successful response", "value": { "id": "4m7x2k9q", "name": "image-generator", "type": "LOAD_BALANCER", "requestUrls": { "base": "https://4m7x2k9q.api.runpod.ai", "health": "https://4m7x2k9q.api.runpod.ai/ping" }, "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 20, "ports": [ "8000/http" ], "env": { "MODEL_NAME": "sdxl" }, "registry": null, "gpu": { "pools": [ "ADA_24" ], "count": 1, "allowedCudaVersions": [], "minCudaVersion": null }, "workers": { "min": 0, "max": 5, "idleTimeout": 5, "initTimeout": null }, "scaling": { "type": "REQUEST_COUNT", "requestCount": 4 }, "dataCenterIds": [ "US-KS-2" ], "networkVolumes": [ "2q9m7x4c" ], "mounts": { "network": [ { "volumeId": "2q9m7x4c" } ], "global": [] }, "timeout": 300000, "flashboot": "OFF", "createdAt": "2026-06-01T12:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateEndpoint", "x-runpod-scope": "serverless:write", "summary": "Update a serverless endpoint", "x-mint": { "metadata": { "description": "Update selected settings on a Runpod Serverless endpoint, including compute, workers, scaling, storage, and container configuration." } }, "description": "Partially updates a serverless endpoint. This is a PATCH: only the\nfields present in the body are changed; omitted fields are left\nuntouched. See `UpdateEndpointRequest` for the full body.\n\nMutable fields: `name`, `gpu`, `cpu`, `workers` (`min`/`max`/`initTimeout`),\n`scaling` (`type`/`value`/`idleTimeout`), `dataCenterIds`,\n`networkVolumes`, `timeout`, `flashboot`, and the\ncontainer settings (`image`, `args`, `disk`, `ports`, `env`,\n`registry`). A patch that leaves the endpoint pulling a private\nAmazon ECR image with no `registry` credential is checked against\nyour ECR delegations as on create (400 when none covers the\nrepository, 403 when the caller's organization role cannot use\ndelegations); a patch that changes neither `image` nor `registry`\nis not.\n\nOmitted compute preserves the current selection. `cpu` completely\nreplaces a CPU endpoint's selection; compute family is immutable.\n`gpu` on CPU, `cpu` on GPU, or both fields returns 400.\n\nReturns `200` with the full updated endpoint. Effect timing differs\nby field: scaling and worker-bound settings (`workers`, `scaling`,\n`timeout`) are applied to the autoscaler promptly, while\ncontainer-affecting changes (e.g. `image`, `env`) create a new\nendpoint release that rolls out as workers cycle — in-flight workers\nkeep the previous version until they are replaced. Track rollout via\n`listEndpointReleases`.\n", "tags": [ "Serverless" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEndpointRequest" }, "examples": { "scaleEndpoint": { "summary": "Scale endpoint", "value": { "workers": { "min": 1, "max": 10, "idleTimeout": 10 }, "scaling": { "type": "QUEUE_DELAY", "queueDelay": 8 } } }, "setInitTimeout": { "summary": "Give workers longer to start", "value": { "workers": { "initTimeout": 1800 } } }, "clearInitTimeout": { "summary": "Clear the initialization timeout", "description": "`null` removes the endpoint setting so the platform default\napplies. Omitting `initTimeout` leaves it unchanged.\n", "value": { "workers": { "initTimeout": null } } }, "changeGpuPoolsKeepingExclusions": { "summary": "Change GPU pools and keep the existing exclusions", "description": "`pools` and `excludedTypes` are replaced together, so both\nare sent. Omitting `excludedTypes` here would clear it.\nRead the current value with `GET /v2/serverless/{id}` first\nand resend the entries that still apply to the new pools —\nan exclusion naming a type that is not in `pools` is\nrejected with 400.\n", "value": { "gpu": { "pools": [ "ADA_24", "AMPERE_80" ], "excludedTypes": [ "NVIDIA L40" ] } } }, "changeCudaOnly": { "summary": "Change a CUDA constraint without touching the GPU selection", "description": "No `pools`, so the pool list and any `excludedTypes` are\nboth left exactly as they are. Same shape for a `count`-only\nchange.\n", "value": { "gpu": { "minCudaVersion": "12.4" } } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" }, "examples": { "endpoint": { "summary": "Successful response", "value": { "id": "4m7x2k9q", "name": "image-generator", "type": "QUEUE", "requestUrls": { "run": "https://api.runpod.ai/v2/4m7x2k9q/run", "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync", "status": "https://api.runpod.ai/v2/4m7x2k9q/status/{job_id}", "stream": "https://api.runpod.ai/v2/4m7x2k9q/stream/{job_id}", "cancel": "https://api.runpod.ai/v2/4m7x2k9q/cancel/{job_id}", "retry": "https://api.runpod.ai/v2/4m7x2k9q/retry/{job_id}", "purgeQueue": "https://api.runpod.ai/v2/4m7x2k9q/purge-queue", "health": "https://api.runpod.ai/v2/4m7x2k9q/health" }, "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 20, "ports": [ "8000/http" ], "env": { "MODEL_NAME": "sdxl" }, "registry": null, "gpu": { "pools": [ "ADA_24" ], "count": 1, "allowedCudaVersions": [], "minCudaVersion": null }, "workers": { "min": 1, "max": 10, "idleTimeout": 10, "initTimeout": null }, "scaling": { "type": "QUEUE_DELAY", "queueDelay": 8 }, "dataCenterIds": [ "US-KS-2" ], "networkVolumes": [ "2q9m7x4c" ], "mounts": { "network": [ { "volumeId": "2q9m7x4c" } ], "global": [] }, "timeout": 300000, "flashboot": "OFF", "createdAt": "2026-06-01T12:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteEndpoint", "x-runpod-scope": "serverless:write", "summary": "Delete a serverless endpoint", "x-mint": { "metadata": { "description": "Permanently delete a Runpod Serverless endpoint, terminate its workers, cancel queued and active jobs, and remove its bound template." } }, "description": "Permanently deletes a serverless endpoint and its bound template.\nThis is irreversible: all workers are terminated and any queued or\nin-progress jobs are cancelled.\n", "tags": [ "Serverless" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless/{id}/workers": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serverless endpoint identifier", "example": "ep_abc123" } ], "get": { "operationId": "listEndpointWorkers", "x-runpod-scope": "serverless:read", "summary": "List serverless endpoint workers", "x-mint": { "metadata": { "description": "List active workers for a Runpod Serverless endpoint with worker status, runtime details, and summary counts grouped by status." } }, "description": "Lists the active workers for a serverless endpoint.\n\n**Returns.** A `200` with a `ListEndpointWorkersResponse`: a\n`workers` array (one entry per active worker, each carrying its `id`,\n`status`, and runtime details) plus a `summary` of worker counts\ngrouped by status. Only currently active workers are included;\nscaled-down workers are not returned.\n\n**How `status` is determined.** Each worker's `status` is derived by\nreconciling the worker pod's lifecycle status with the endpoint's\nlive job-queue view (which workers are actively serving requests).\nWhen the job-queue view is unavailable, the response degrades\ngracefully: the shape is unchanged, but each `status` and the summary\ncounts fall back to pod lifecycle alone.\n", "tags": [ "Serverless" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointWorkersResponse" }, "examples": { "workers": { "summary": "Successful response", "value": { "endpointVersion": 4, "summary": { "running": 1, "idle": 1, "initializing": 0, "throttled": 0, "unhealthy": 0, "total": 2 }, "workers": [ { "id": "8g3n5t6r", "status": "RUNNING", "isStale": false, "version": 4, "gpuCount": 1, "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "uptimeSeconds": 3600, "gpuTypeId": "NVIDIA GeForce RTX 4090", "dataCenterId": "US-KS-2", "startedAt": "2026-06-01T12:05:00Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless/{id}/releases": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serverless endpoint identifier", "example": "ep_abc123" } ], "get": { "operationId": "listEndpointReleases", "x-runpod-scope": "serverless:read", "summary": "List serverless endpoint releases", "x-mint": { "metadata": { "description": "List a Serverless endpoint's release history, configuration changes, build IDs, and current worker rollout status, newest release first." } }, "description": "Returns the endpoint's release history (newest first) plus a rollout\nsummary of how many workers are running the current version. Each\nrelease is a versioned configuration snapshot with a `diff` of what\nchanged; build-driven releases carry a `buildId` (fetch build detail via\nthe builds sub-routes).\n\nReleases are cursor-paginated newest-first; an omitted `limit`\ndefaults to 1000. The rollout summary always describes the endpoint's\ncurrent state, independent of the page requested.\n", "tags": [ "Serverless" ], "parameters": [ { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointReleasesResponse" }, "examples": { "releases": { "summary": "Successful response", "value": { "endpointVersion": 4, "rollout": { "inProgress": true, "workersOnLatest": 1, "workersTotal": 2, "percentOnLatest": 50 }, "releases": [ { "id": "5r9x2m7q", "version": 4, "source": "MANUAL", "buildId": null, "createdByUserId": null, "workerCount": 2, "createdAt": "2026-06-01T12:10:00Z", "diff": [ { "field": "workers.max", "old": 5, "new": 10 } ] } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless/{id}/builds": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serverless endpoint identifier", "example": "ep_abc123" } ], "get": { "operationId": "listEndpointBuilds", "x-runpod-scope": "serverless:read", "summary": "List serverless endpoint builds", "x-mint": { "metadata": { "description": "List a Runpod Serverless endpoint's GitHub build history, newest first, capped to the 100 most recent builds, with older builds fetchable by ID." } }, "description": "Returns the endpoint's GitHub build history, newest first (Runpod\nGitHub-build integration), cursor-paginated; an omitted `limit`\ndefaults to 100, so a bare request returns at most the 100 most\nrecent builds. Any build can also be fetched by id via\n`GET /v2/serverless/{id}/builds/{buildId}`. Stream a build's logs via\n`/v2/serverless/{id}/builds/{buildId}/logs`.\n", "tags": [ "Serverless" ], "parameters": [ { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimitBuilds" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointBuildsResponse" }, "examples": { "builds": { "summary": "Successful response", "value": { "builds": [ { "id": "build_abc123", "status": "COMPLETED", "commitHash": "abc1234", "commitMessage": "bump model", "branch": "main", "commitDate": "2026-06-01T12:00:00Z", "imageName": "registry.runpod.net/repo:abc1234", "startedAt": "2026-06-01T12:00:05Z", "completedAt": "2026-06-01T12:04:31Z", "error": null } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless/{id}/builds/{buildId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serverless endpoint identifier", "example": "ep_abc123" }, { "name": "buildId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "GitHub build identifier (from GET /v2/serverless/{id}/builds or a release's `buildId`)", "example": "build_abc123" } ], "get": { "operationId": "getEndpointBuild", "x-runpod-scope": "serverless:read", "summary": "Get a serverless endpoint build", "x-mint": { "metadata": { "description": "Retrieve a single GitHub build for a Runpod Serverless endpoint by its build ID, returning that build regardless of how old it is." } }, "description": "Returns one of the endpoint's GitHub builds by id, regardless of age —\nno need to page through `GET /v2/serverless/{id}/builds` to reach it.\n", "tags": [ "Serverless" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Build" }, "examples": { "build": { "summary": "Successful response", "value": { "id": "build_abc123", "status": "COMPLETED", "commitHash": "abc1234", "commitMessage": "bump model", "branch": "main", "commitDate": "2026-06-01T12:00:00Z", "imageName": "registry.runpod.net/repo:abc1234", "startedAt": "2026-06-01T12:00:05Z", "completedAt": "2026-06-01T12:04:31Z", "error": null } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless/{id}/metrics/requests": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serverless endpoint identifier", "example": "ep_abc123" } ], "get": { "operationId": "getEndpointRequestMetrics", "x-runpod-scope": "serverless:read", "summary": "Get serverless endpoint request metrics", "x-mint": { "metadata": { "description": "Get request counts, execution time, and queue delay for a Runpod Serverless endpoint as a time series." } }, "description": "Returns the request series shown on the endpoint's Metrics tab in the console.\n\n**Window.** `startTime` is inclusive and `endTime` is exclusive. Both are\noptional: `endTime` defaults to now and `startTime` to 24 hours before\n`endTime`, rounded down to the start of an `interval` bucket. An\n`endTime` in the future is treated as now. Metrics are kept for 90 days,\nso `startTime` must be within the last 90 days.\n\n**Interval.** Each record covers one `interval`-sized bucket, aligned to\nUTC.\n\n**Paging.** Records are oldest first, at most `limit` (default 1000) per\npage. Follow `pagination.nextCursor` while `pagination.hasNextPage` is\ntrue. The cursor keeps the first page's window, so `startTime`,\n`endTime`, and `interval` can be left out on later pages; if sent, they\nmust match the first page or the cursor is rejected with 422.\n\n**Sparse series.** Buckets with no activity are omitted, not zero-filled,\nso `records` can be shorter than the number of buckets in the window, or\nempty.\n\n**Units.** Durations are milliseconds. `executionTimeMs` is the time a\nworker spent running a request; `delayTimeMs` is the time a request\nwaited in the queue before a worker picked it up.\n", "tags": [ "Serverless" ], "parameters": [ { "$ref": "#/components/parameters/MetricsStartTime" }, { "$ref": "#/components/parameters/MetricsEndTime" }, { "$ref": "#/components/parameters/MetricsInterval" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointRequestMetricsResponse" }, "examples": { "metrics": { "summary": "Successful response", "value": { "startTime": "2026-10-11T00:00:00Z", "endTime": "2026-10-12T00:00:00Z", "interval": "1h", "records": [ { "time": "2026-10-11T13:00:00Z", "requests": 120, "completed": 117, "failed": 3, "retries": 2, "executionTimeMs": { "min": 210, "max": 9400, "total": 182400, "p70": 1500, "p90": 3100, "p95": 4800, "p98": 7700 }, "delayTimeMs": { "min": 4, "max": 2100, "total": 15600, "p70": 90, "p90": 310, "p95": 820, "p98": 1500 } } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless/{id}/metrics/cold-starts": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serverless endpoint identifier", "example": "ep_abc123" } ], "get": { "operationId": "getEndpointColdStartMetrics", "x-runpod-scope": "serverless:read", "summary": "Get serverless endpoint cold start metrics", "x-mint": { "metadata": { "description": "Get cold start counts and durations for a Runpod Serverless endpoint as a time series." } }, "description": "Returns the cold start series shown on the endpoint's Metrics tab in the console.\n\n**Window.** `startTime` is inclusive and `endTime` is exclusive. Both are\noptional: `endTime` defaults to now and `startTime` to 24 hours before\n`endTime`, rounded down to the start of an `interval` bucket. An\n`endTime` in the future is treated as now. Metrics are kept for 90 days,\nso `startTime` must be within the last 90 days.\n\n**Interval.** Each record covers one `interval`-sized bucket, aligned to\nUTC.\n\n**Paging.** Records are oldest first, at most `limit` (default 1000) per\npage. Follow `pagination.nextCursor` while `pagination.hasNextPage` is\ntrue. The cursor keeps the first page's window, so `startTime`,\n`endTime`, and `interval` can be left out on later pages; if sent, they\nmust match the first page or the cursor is rejected with 422.\n\n**Sparse series.** Buckets with no activity are omitted, not zero-filled,\nso `records` can be shorter than the number of buckets in the window, or\nempty.\n\n**Units.** `durationMs` is how long each cold start took, in milliseconds.\n", "tags": [ "Serverless" ], "parameters": [ { "$ref": "#/components/parameters/MetricsStartTime" }, { "$ref": "#/components/parameters/MetricsEndTime" }, { "$ref": "#/components/parameters/MetricsInterval" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointColdStartMetricsResponse" }, "examples": { "metrics": { "summary": "Successful response", "value": { "startTime": "2026-10-11T00:00:00Z", "endTime": "2026-10-12T00:00:00Z", "interval": "1h", "records": [ { "time": "2026-10-11T13:00:00Z", "count": 2, "durationMs": { "min": 8200, "max": 11900, "total": 20100, "p70": 11900, "p90": 11900, "p95": 11900, "p98": 11900 } } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless/{id}/metrics/workers": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serverless endpoint identifier", "example": "ep_abc123" } ], "get": { "operationId": "getEndpointWorkerMetrics", "x-runpod-scope": "serverless:read", "summary": "Get serverless endpoint worker metrics", "x-mint": { "metadata": { "description": "Get worker counts by state for a Runpod Serverless endpoint as a time series." } }, "description": "Returns the worker state series shown on the endpoint's Metrics tab in the console.\nFor the current worker list, use `GET /v2/serverless/{id}/workers`.\n\n**Window.** `startTime` is inclusive and `endTime` is exclusive. Both are\noptional: `endTime` defaults to now and `startTime` to 24 hours before\n`endTime`, rounded down to the start of an `interval` bucket. An\n`endTime` in the future is treated as now. Metrics are kept for 90 days,\nso `startTime` must be within the last 90 days.\n\n**Interval.** Each record covers one `interval`-sized bucket, aligned to\nUTC.\n\n**Paging.** Records are oldest first, at most `limit` (default 1000) per\npage. Follow `pagination.nextCursor` while `pagination.hasNextPage` is\ntrue. The cursor keeps the first page's window, so `startTime`,\n`endTime`, and `interval` can be left out on later pages; if sent, they\nmust match the first page or the cursor is rejected with 422.\n\n**Sparse series.** Buckets with no activity are omitted, not zero-filled,\nso `records` can be shorter than the number of buckets in the window, or\nempty.\n\n**Snapshots.** Each record holds the last worker-count snapshot in its\nbucket, as point-in-time counts.\n", "tags": [ "Serverless" ], "parameters": [ { "$ref": "#/components/parameters/MetricsStartTime" }, { "$ref": "#/components/parameters/MetricsEndTime" }, { "$ref": "#/components/parameters/MetricsInterval" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointWorkerMetricsResponse" }, "examples": { "metrics": { "summary": "Successful response", "value": { "startTime": "2026-10-11T00:00:00Z", "endTime": "2026-10-12T00:00:00Z", "interval": "1h", "records": [ { "time": "2026-10-11T13:00:00Z", "running": 3, "idle": 1, "initializing": 0, "throttled": 0, "unhealthy": 0 } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/serverless/{id}/workers/{workerId}/logs": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serverless endpoint identifier", "example": "ep_abc123" }, { "name": "workerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Worker identifier (from GET /v2/serverless/{id}/workers)", "example": "worker_abc" } ], "get": { "operationId": "getWorkerLogs", "x-runpod-scope": "serverless:read", "summary": "Stream serverless worker logs", "x-mint": { "metadata": { "description": "Stream a Runpod Serverless worker's logs in real time as Server-Sent Events, with resumable reconnects via Last-Event-ID." } }, "description": "Streams a serverless worker's logs as Server-Sent Events. The `source`\nquery parameter selects which log source to include.\n\nThe SSE `data` payload shape is:\n`{ \"source\": \"container\", \"line\": \"...\", \"ts\": \"...\" }`.\nLog-event `id` values are the event `ts` timestamp so browser/EventSource\nreconnects can resume with `Last-Event-ID`.\n", "tags": [ "Serverless" ], "parameters": [ { "$ref": "#/components/parameters/LogSourceParam" }, { "$ref": "#/components/parameters/LogTail" }, { "$ref": "#/components/parameters/LogSince" }, { "$ref": "#/components/parameters/LogLastEventID" } ], "responses": { "200": { "description": "Worker log event stream", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Cache-Control": { "schema": { "type": "string" }, "description": "Always `no-cache` for SSE responses." }, "Connection": { "schema": { "type": "string" }, "description": "Always `keep-alive` to hold the SSE stream open." }, "X-Accel-Buffering": { "schema": { "type": "string" }, "description": "Always `no` to disable proxy buffering of the SSE stream." } }, "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream. Each event includes an `id:` line and a JSON `data:` payload with `source`, `line`, and `ts` fields." }, "examples": { "logLine": { "summary": "Successful response", "value": "id: 2026-06-01T12:05:04Z/000000000042\ndata: {\"ts\":\"2026-06-01T12:05:04Z\",\"source\":\"container\",\"line\":\"Worker ready.\"}\n" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/templates": { "get": { "operationId": "listTemplates", "x-runpod-scope": "templates:read", "summary": "List templates", "description": "Returns templates owned by the authenticated user (including\nteam/organization-scoped ones), cursor-paginated; an omitted `limit`\ndefaults to 1000. Follow `pagination.nextCursor` until `hasNextPage`\nis false.\n", "x-mint": { "metadata": { "description": "List all reusable Runpod templates owned by the authenticated user, including Pod and Serverless container configuration details." } }, "tags": [ "Templates" ], "parameters": [ { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" }, "examples": { "templates": { "summary": "Successful response", "value": { "templates": [ { "id": "9x4m2p7v", "name": "PyTorch GPU Template", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "ports": [ "8888/http" ], "env": { "JUPYTER_ENABLE_LAB": "yes" }, "registry": null, "serverless": false, "public": false, "category": "NVIDIA", "startSsh": true, "startJupyter": false, "allowedCudaVersions": [] } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createTemplate", "x-runpod-scope": "templates:write", "summary": "Create a template", "x-mint": { "metadata": { "description": "Create a reusable Runpod template for Pod and Serverless container settings, including images, storage, ports, environment, and mounts." } }, "description": "Creates a reusable container-configuration preset — image, disk,\nports, env, registry, and mount settings — for pods and serverless\nendpoints. Pass its ID as `templateId` to `createPod` or\n`createEndpoint`, or spread its fields into the request body\ndirectly. Returns the created template.\n", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" }, "examples": { "podTemplate": { "summary": "Pod template", "value": { "name": "PyTorch GPU Template", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "category": "NVIDIA", "disk": 50, "ports": [ "8888/http" ], "env": { "JUPYTER_ENABLE_LAB": "yes" }, "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "serverless": false, "public": false } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" }, "examples": { "template": { "summary": "Successful response", "value": { "id": "9x4m2p7v", "name": "PyTorch GPU Template", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "ports": [ "8888/http" ], "env": { "JUPYTER_ENABLE_LAB": "yes" }, "registry": null, "serverless": false, "public": false, "category": "NVIDIA", "startSsh": true, "startJupyter": false, "allowedCudaVersions": [] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/templates/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tpl_abc" } ], "get": { "operationId": "getTemplate", "x-runpod-scope": "templates:read", "summary": "Get a template", "x-mint": { "metadata": { "description": "Retrieve the complete configuration of an owned or public Runpod template by ID, including settings used to create Pods and endpoints." } }, "description": "Returns the full configuration of a single template by ID. Serves\nboth templates you own and public catalog templates — everything you\ncan read. Updates and deletes remain restricted to templates you own.\n", "tags": [ "Templates" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" }, "examples": { "template": { "summary": "Successful response", "value": { "id": "9x4m2p7v", "name": "PyTorch GPU Template", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "ports": [ "8888/http" ], "env": { "JUPYTER_ENABLE_LAB": "yes" }, "registry": null, "serverless": false, "public": false, "category": "NVIDIA", "startSsh": true, "startJupyter": false, "allowedCudaVersions": [] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateTemplate", "x-runpod-scope": "templates:write", "summary": "Update a template", "x-mint": { "metadata": { "description": "Update selected fields on a Runpod template while preserving omitted settings, with ownership rules and behavior for existing resources." } }, "description": "Partially updates a template. This is a PATCH: only the fields\npresent in the body are changed; omitted fields are left untouched.\nSee `UpdateTemplateRequest` for the full body.\n\nMutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`,\n`registry`, `mounts`, `serverless`, `public`, and `category`.\n\nOnly the template's owner can update it (authenticated via the\nrequest's API key); public catalog templates are readable via GET\nbut return `404` here. Returns `200` with the full updated template. Pods and\nendpoints already created from this template are not changed\nretroactively — the template is a snapshot applied at creation time.\n", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateRequest" }, "examples": { "renameTemplate": { "summary": "Rename template", "value": { "name": "Renamed PyTorch Template" } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" }, "examples": { "template": { "summary": "Successful response", "value": { "id": "9x4m2p7v", "name": "Renamed PyTorch Template", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "mounts": { "persistent": { "size": 20, "path": "/workspace" } }, "ports": [ "8888/http" ], "env": { "JUPYTER_ENABLE_LAB": "yes" }, "registry": null, "serverless": false, "public": false, "category": "NVIDIA", "startSsh": true, "startJupyter": false, "allowedCudaVersions": [] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteTemplate", "x-runpod-scope": "templates:write", "summary": "Delete a template", "x-mint": { "metadata": { "description": "Permanently delete an owned Runpod template by ID and understand restrictions when Pods or Serverless endpoints still reference it." } }, "description": "Permanently deletes a template by ID. Only the template's owner can\ndelete it — public catalog templates return `404` here. Rejected if\nthe template is currently referenced by a pod (see that pod's\n`template` field) or bound to a serverless endpoint.\n", "tags": [ "Templates" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Template is in use by a pod or serverless endpoint and cannot be deleted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/templates/{id}/readme": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tpl_abc" } ], "get": { "operationId": "getTemplateReadme", "x-runpod-scope": "templates:read", "summary": "Get a template README", "x-mint": { "metadata": { "description": "Retrieve the Markdown README of an owned or public Runpod template, with setup and usage instructions." } }, "description": "Returns the template's README as raw Markdown. Serves the same\ntemplates as `GET /v2/templates/{id}`: templates you own and public\ncatalog templates. Returns `404` when the template does not exist,\nis not readable by you, or has no README.\n", "tags": [ "Templates" ], "responses": { "200": { "$ref": "#/components/responses/TemplateReadme" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/network-volumes": { "get": { "operationId": "listNetworkVolumes", "x-runpod-scope": "volumes:read", "summary": "List network volumes", "x-mint": { "metadata": { "description": "List all network volumes owned by the authenticated Runpod user, including each volume's size, data center, and storage tier." } }, "description": "Returns network volumes owned by the authenticated user,\ncursor-paginated newest-first; an omitted `limit` defaults to 1000.\nFollow `pagination.nextCursor` until `hasNextPage` is false.\n", "tags": [ "Network Volumes" ], "parameters": [ { "$ref": "#/components/parameters/ResourceFilters" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNetworkVolumesResponse" }, "examples": { "networkVolumes": { "summary": "Successful response", "value": { "networkVolumes": [ { "id": "2q9m7x4c", "name": "training-dataset", "size": 100, "dataCenter": "US-KS-2", "type": "HIGH_PERFORMANCE" } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createNetworkVolume", "x-runpod-scope": "volumes:write", "summary": "Create a network volume", "x-mint": { "metadata": { "description": "Create a persistent Runpod network volume with a name, size, data center, and storage tier for use by Pods and Serverless workers." } }, "description": "Provisions a new network volume — persistent, network-attached\nstorage that can be mounted into pods and serverless workers.\nRequired inputs are `name`, `size` (in GB), and `dataCenter`; an\noptional `type` selects the storage tier and is immutable after\ncreation. See `CreateNetworkVolumeRequest` for the size bounds and\ntier options.\n\nThis creates a billable persistent resource that keeps incurring\nstorage charges until it is deleted. Returns `201` with the created\nnetwork volume, including its assigned `id`.\n", "tags": [ "Network Volumes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNetworkVolumeRequest" }, "examples": { "networkVolume": { "summary": "Network volume", "value": { "name": "training-dataset", "dataCenter": "US-KS-2", "size": 50, "type": "HIGH_PERFORMANCE" } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkVolume" }, "examples": { "networkVolume": { "summary": "Successful response", "value": { "id": "2q9m7x4c", "name": "training-dataset", "size": 50, "dataCenter": "US-KS-2", "type": "HIGH_PERFORMANCE" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/network-volumes/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Network volume identifier", "example": "agv6w2qcg7" } ], "get": { "operationId": "getNetworkVolume", "x-runpod-scope": "volumes:read", "summary": "Get a network volume", "x-mint": { "metadata": { "description": "Retrieve a Runpod network volume by ID with its name, size, data center, storage tier, and current resource details." } }, "description": "Returns a single network volume by ID.", "tags": [ "Network Volumes" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkVolume" }, "examples": { "networkVolume": { "summary": "Successful response", "value": { "id": "2q9m7x4c", "name": "training-dataset", "size": 100, "dataCenter": "US-KS-2", "type": "HIGH_PERFORMANCE" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateNetworkVolume", "x-runpod-scope": "volumes:write", "summary": "Update a network volume", "x-mint": { "metadata": { "description": "Update a Runpod network volume's mutable fields, such as its name or size. Size can only be increased, never reduced." } }, "description": "Updates mutable fields on a network volume. Only provided fields are changed.\nNote: `size` may only increase; attempts to reduce size will be rejected.\n", "tags": [ "Network Volumes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNetworkVolumeRequest" }, "examples": { "resizeNetworkVolume": { "summary": "Resize network volume", "value": { "size": 200 } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkVolume" }, "examples": { "networkVolume": { "summary": "Successful response", "value": { "id": "2q9m7x4c", "name": "training-dataset", "size": 200, "dataCenter": "US-KS-2", "type": "HIGH_PERFORMANCE" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Invalid request body or size decrease attempted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteNetworkVolume", "x-runpod-scope": "volumes:write", "summary": "Delete a network volume", "x-mint": { "metadata": { "description": "Permanently delete a Runpod network volume, release its persistent storage, and confirm the removed volume in the response." } }, "description": "Permanently deletes a network volume and releases its storage.", "tags": [ "Network Volumes" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The volume was created less than five minutes ago. Retry after the time given in the detail.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/global-volumes": { "get": { "operationId": "listGlobalVolumes", "x-runpod-scope": "volumes:read", "summary": "List global volumes", "x-mint": { "metadata": { "description": "List global volumes owned by your Runpod account through the REST API, using cursor pagination to retrieve additional results." } }, "description": "Returns global volumes owned by the authenticated user,\ncursor-paginated newest-first; an omitted `limit` defaults to 1000.\nFollow `pagination.nextCursor` until `hasNextPage` is false.\n", "tags": [ "Global Volumes" ], "parameters": [ { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGlobalVolumesResponse" }, "examples": { "globalVolumes": { "summary": "Successful response", "value": { "globalVolumes": [ { "id": "gsb_abc", "name": "training-data", "createdAt": "2026-09-24T00:00:00Z", "createdByUserId": "user_123" } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createGlobalVolume", "x-runpod-scope": "volumes:write", "summary": "Create a global volume", "x-mint": { "metadata": { "description": "Create a named Runpod global volume through the REST API for storage that Pods and Serverless workers can access across data centers." } }, "description": "Provisions a new global volume — storage that mounts into workloads\nin any data center. Only a `name` is required; storage is provisioned\nfor you. Accounts have a cap on how many global volumes they can\nhold; creating one past it fails with `400`.\n\nReturns `201` with the created global volume, including its assigned\n`id`.\n", "tags": [ "Global Volumes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGlobalVolumeRequest" }, "examples": { "globalVolume": { "summary": "Global volume", "value": { "name": "training-data" } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalVolume" }, "examples": { "globalVolume": { "summary": "Successful response", "value": { "id": "gsb_abc", "name": "training-data", "createdAt": "2026-09-24T00:00:00Z", "createdByUserId": "user_123" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/global-volumes/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Global volume identifier", "example": "gsb_abc" } ], "get": { "operationId": "getGlobalVolume", "x-runpod-scope": "volumes:read", "summary": "Get a global volume", "x-mint": { "metadata": { "description": "Retrieve a Runpod global volume by its ID through the REST API, including its name, creation time, and the user who created it." } }, "description": "Returns a single global volume by ID.", "tags": [ "Global Volumes" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalVolume" }, "examples": { "globalVolume": { "summary": "Successful response", "value": { "id": "gsb_abc", "name": "training-data", "createdAt": "2026-09-24T00:00:00Z", "createdByUserId": "user_123" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateGlobalVolume", "x-runpod-scope": "volumes:write", "summary": "Update a global volume", "x-mint": { "metadata": { "description": "Rename an existing Runpod global volume by ID through the REST API, updating its name while leaving omitted fields unchanged." } }, "description": "Updates mutable fields on a global volume. Only provided fields are changed.", "tags": [ "Global Volumes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGlobalVolumeRequest" }, "examples": { "renameGlobalVolume": { "summary": "Rename global volume", "value": { "name": "renamed-volume" } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalVolume" }, "examples": { "globalVolume": { "summary": "Successful response", "value": { "id": "gsb_abc", "name": "renamed-volume", "createdAt": "2026-09-24T00:00:00Z", "createdByUserId": "user_123" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteGlobalVolume", "x-runpod-scope": "volumes:write", "summary": "Delete a global volume", "x-mint": { "metadata": { "description": "Permanently delete a Runpod global volume and its stored data through the REST API after removing Pod and Serverless attachments." } }, "description": "Permanently deletes a global volume and its stored data. Fails with\n`409` while the volume is still mounted: terminate every pod that\nmounts it (stopped pods count) and detach it from every serverless\nendpoint first. Nothing is detached or terminated on your behalf.\n", "tags": [ "Global Volumes" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "The volume is still mounted by a pod or serverless endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/registries": { "get": { "operationId": "listRegistries", "x-runpod-scope": "secrets:read", "summary": "List container registries", "x-mint": { "metadata": { "description": "List all container registry credentials owned by the authenticated Runpod user, with secret usernames and passwords excluded." } }, "description": "Returns all container registry credentials owned by the authenticated user.", "tags": [ "Registries" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRegistriesResponse" }, "examples": { "registries": { "summary": "Successful response", "value": { "registries": [ { "id": "6n2k8v4d", "name": "dockerhub-private" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createRegistry", "x-runpod-scope": "secrets:write", "summary": "Create a container registry credential", "x-mint": { "metadata": { "description": "Store credentials for a private container registry in Runpod for authenticated image pulls while keeping the saved secrets write-only." } }, "description": "Stores credentials for a private container registry. Credentials are write-only.", "tags": [ "Registries" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRegistryRequest" }, "examples": { "dockerHubRegistry": { "summary": "Docker Hub registry", "value": { "name": "dockerhub-private", "username": "runpod-user", "password": "correct-horse-battery-staple" } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registry" }, "examples": { "registry": { "summary": "Successful response", "value": { "id": "6n2k8v4d", "name": "dockerhub-private" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/registries/{id}": { "x-runpod-sensitive-request": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "reg_abc" } ], "get": { "operationId": "getRegistry", "x-runpod-scope": "secrets:read", "summary": "Get a container registry credential", "x-mint": { "metadata": { "description": "Retrieve a Runpod container registry credential by ID while keeping stored usernames and passwords excluded from the response." } }, "description": "Returns a single container registry credential by ID. `username` and\n`password` are never included in the response — credentials are\nwrite-only, matching `createRegistry`.\n", "tags": [ "Registries" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registry" }, "examples": { "registry": { "summary": "Successful response", "value": { "id": "6n2k8v4d", "name": "dockerhub-private" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateRegistry", "x-runpod-scope": "secrets:write", "summary": "Update a container registry credential", "x-mint": { "metadata": { "description": "Rotate the username and password of a Runpod container registry credential in place, without repointing the Pods, templates, and Serverless endpoints that use it." } }, "description": "Replaces the username and password stored in a container registry\ncredential. The ID and `name` stay the same, so every pod, template,\nand Serverless endpoint that references the credential keeps\nreferencing it and needs no change.\n\nSend both `username` and `password`, even when only one of them\nchanged. They are stored together and are write-only, so there is no\nstored value to keep for an omitted field.\n\nThe new credentials apply to image pulls that start after the update.\nRunning pods and workers keep the image they already pulled.\n", "tags": [ "Registries" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRegistryRequest" }, "examples": { "rotatePassword": { "summary": "Rotate the password", "value": { "username": "runpod-user", "password": "new-correct-horse-battery-staple" } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registry" }, "examples": { "registry": { "summary": "Successful response", "value": { "id": "6n2k8v4d", "name": "dockerhub-private" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteRegistry", "x-runpod-scope": "secrets:write", "summary": "Delete a container registry credential", "x-mint": { "metadata": { "description": "Delete a Runpod container registry credential by ID and understand how active Pods and templates that reference it are handled." } }, "description": "Permanently deletes a container registry credential by ID. Rejected\nif any pod currently uses this credential to pull its image.\nTemplates that reference it are not part of that check — they\nsilently lose the reference (`registry` becomes null) instead of\nblocking the delete.\n", "tags": [ "Registries" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Registry credential is in use by a pod and cannot be deleted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/registries/delegations": { "get": { "operationId": "listDelegations", "x-runpod-scope": "secrets:read", "summary": "List all ECR delegations", "x-mint": { "metadata": { "description": "List the Amazon ECR delegations that let Runpod pull private container images from your AWS registries." } }, "tags": [ "Registries" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDelegationsResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createDelegation", "x-runpod-scope": "secrets:write", "summary": "Register an ECR delegation", "x-mint": { "metadata": { "description": "Register an Amazon ECR delegation that lets Runpod pull private container images from your AWS registry for Pods and Serverless endpoints." } }, "tags": [ "Registries" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDelegationRequest" } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Delegation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcrDelegation" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/registries/delegations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "deleg_abc" } ], "delete": { "operationId": "revokeDelegation", "x-runpod-scope": "secrets:write", "summary": "Revoke an ECR delegation", "x-mint": { "metadata": { "description": "Revoke an Amazon ECR delegation so Runpod can no longer pull private container images from that AWS registry on your behalf." } }, "tags": [ "Registries" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Delegation revoked" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Delegation not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/catalog/gpus": { "get": { "operationId": "listGpuTypes", "x-runpod-scope": "catalog:read", "summary": "List GPU types", "x-mint": { "metadata": { "description": "List available Runpod GPU types with pricing and optional availability filters by product, country, and deployment context." } }, "description": "Returns available GPU types with pricing. Availability is included only when requested with include=AVAILABILITY, which requires `product` — stock differs by product context. With countryCodes, the list is narrowed to GPU types deployable in those countries, so \"this geography + this chip\" resolves in one read.", "tags": [ "Catalog" ], "parameters": [ { "$ref": "#/components/parameters/CatalogIncludeParam" }, { "$ref": "#/components/parameters/GpuProductFilter" }, { "$ref": "#/components/parameters/GpuCountFilter" }, { "$ref": "#/components/parameters/GpuCloudFilter" }, { "$ref": "#/components/parameters/CountryCodesFilter" }, { "$ref": "#/components/parameters/CudaVersionsFilter" }, { "$ref": "#/components/parameters/MinCudaVersionFilter" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGpuTypesResponse" }, "examples": { "gpus": { "summary": "Successful response", "value": { "gpus": [ { "id": "NVIDIA GeForce RTX 4090", "name": "RTX 4090", "pool": "ADA_24", "manufacturer": "NVIDIA", "memory": 24, "secure": true, "community": true, "price": { "secure": 0.44, "community": 0.31, "serverless": 1.1 }, "maxCount": { "secure": 8, "community": 4 }, "availability": "HIGH", "dataCenters": [ { "id": "US-KS-2", "name": "US Kansas 2", "availability": "HIGH" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/catalog/gpus/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "NVIDIA GeForce RTX 4090" } ], "get": { "operationId": "getGpuType", "x-runpod-scope": "catalog:read", "summary": "Get a GPU type", "x-mint": { "metadata": { "description": "Retrieve one Runpod GPU type with pricing and optional availability details for a specified product and deployment context." } }, "description": "Returns a single GPU type with pricing. Availability details are included only when requested with include=AVAILABILITY, which requires `product` — stock differs by product context.", "tags": [ "Catalog" ], "parameters": [ { "$ref": "#/components/parameters/CatalogIncludeParam" }, { "$ref": "#/components/parameters/GpuProductFilter" }, { "$ref": "#/components/parameters/GpuCountFilter" }, { "$ref": "#/components/parameters/GpuCloudFilter" }, { "$ref": "#/components/parameters/CountryCodesFilter" }, { "$ref": "#/components/parameters/CudaVersionsFilter" }, { "$ref": "#/components/parameters/MinCudaVersionFilter" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpuType" }, "examples": { "gpu": { "summary": "Successful response", "value": { "id": "NVIDIA GeForce RTX 4090", "name": "RTX 4090", "pool": "ADA_24", "manufacturer": "NVIDIA", "memory": 24, "secure": true, "community": true, "price": { "secure": 0.44, "community": 0.31, "serverless": 1.1 }, "maxCount": { "secure": 8, "community": 4 }, "availability": "HIGH", "dataCenters": [ { "id": "US-KS-2", "name": "US Kansas 2", "availability": "HIGH" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/catalog/cpus": { "get": { "operationId": "listCpuTypes", "x-runpod-scope": "catalog:read", "summary": "List CPU types", "x-mint": { "metadata": { "description": "List available Runpod CPU types with pricing and optional availability details for a specified product and deployment context." } }, "description": "Returns available CPU flavors. Availability is included only when requested with include=AVAILABILITY, which requires `product` — stock differs by product context.", "tags": [ "Catalog" ], "parameters": [ { "$ref": "#/components/parameters/CatalogIncludeParam" }, { "$ref": "#/components/parameters/CpuProductFilter" }, { "$ref": "#/components/parameters/CpuVCPUCountFilter" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCpuTypesResponse" }, "examples": { "cpus": { "summary": "Successful response", "value": { "cpus": [ { "id": "cpu3c-2-4", "name": "Compute-Optimized", "group": "Gen 3", "vcpu": { "min": 2, "max": 32 }, "ramGbPerVcpu": 2.5, "price": { "securePerVcpu": 0.04, "serverlessPerVcpu": 0.03 }, "availability": "MEDIUM", "dataCenters": [ { "id": "US-KS-2", "name": "US Kansas 2", "availability": "MEDIUM" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/catalog/cpus/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "cpu5c" } ], "get": { "operationId": "getCpuType", "x-runpod-scope": "catalog:read", "summary": "Get a CPU type", "x-mint": { "metadata": { "description": "Retrieve one Runpod CPU type with pricing and optional availability details for a specified product and deployment context." } }, "description": "Returns a single CPU type with pricing. Availability details are included only when requested with include=AVAILABILITY, which requires `product` — stock differs by product context.", "tags": [ "Catalog" ], "parameters": [ { "$ref": "#/components/parameters/CatalogIncludeParam" }, { "$ref": "#/components/parameters/CpuProductFilter" }, { "$ref": "#/components/parameters/CpuVCPUCountFilter" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CpuType" }, "examples": { "cpu": { "summary": "Successful response", "value": { "id": "cpu3c-2-4", "name": "Compute-Optimized", "group": "Gen 3", "vcpu": { "min": 2, "max": 32 }, "ramGbPerVcpu": 2.5, "price": { "securePerVcpu": 0.04, "serverlessPerVcpu": 0.03 }, "availability": "MEDIUM", "dataCenters": [ { "id": "US-KS-2", "name": "US Kansas 2", "availability": "MEDIUM" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/catalog/datacenters": { "get": { "operationId": "listDataCenters", "x-runpod-scope": "catalog:read", "summary": "List data centers", "x-mint": { "metadata": { "description": "List Runpod data centers with region, compliance, storage, networking, and optional GPU or CPU availability details." } }, "description": "Returns available data center locations with region, compliance, supported network volume tiers, and global networking support. Use include=GPU_AVAILABILITY or include=CPU_AVAILABILITY to add per-resource availability arrays to each data center. The regions, networkVolumeTypes, compliance, and globalNetwork query parameters filter the list before it is returned.\n", "tags": [ "Catalog" ], "parameters": [ { "name": "include", "in": "query", "required": false, "description": "Comma-separated optional expansions. Supported value: GPU_AVAILABILITY, CPU_AVAILABILITY.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataCenterInclude" }, "example": [ "GPU_AVAILABILITY" ] } }, { "name": "regions", "in": "query", "required": false, "description": "Comma-separated DataCenterRegion enum values. Values within this filter use OR semantics. Different filter families combine with AND.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataCenterRegion" }, "example": [ "EUROPE", "ASIA" ] } }, { "name": "networkVolumeTypes", "in": "query", "required": false, "description": "Comma-separated volume types. Supported values: STANDARD, HIGH_PERFORMANCE. Values within this filter use AND semantics; volumes=STANDARD,HIGH_PERFORMANCE requires both storage types. Different filter families combine with AND.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeType" }, "example": [ "STANDARD", "HIGH_PERFORMANCE" ] } }, { "name": "compliance", "in": "query", "required": false, "description": "Comma-separated Compliance enum values. Values within this filter use AND semantics; compliance=GDPR,SOC_2_TYPE_2 requires both certifications. Different filter families combine with AND.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Compliance" }, "example": [ "GDPR", "SOC_2_TYPE_2" ] } }, { "name": "globalNetwork", "in": "query", "required": false, "description": "Filter by global networking support. true returns only data centers that support global networking; false only those that do not. Different filter families combine with AND.", "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDataCentersResponse" }, "examples": { "dataCenters": { "summary": "Successful response", "value": { "dataCenters": [ { "id": "US-KS-2", "name": "US Kansas 2", "region": "NORTH_AMERICA", "globalNetwork": true, "networkVolumeTypes": [ "STANDARD", "HIGH_PERFORMANCE" ], "compliance": [ "SOC_2_TYPE_2", "ISO_IEC_27001" ], "gpuAvailability": [ { "id": "NVIDIA GeForce RTX 4090", "name": "RTX 4090", "availability": "HIGH" } ], "cpuAvailability": [ { "id": "cpu3c-2-4", "name": "Compute-Optimized", "availability": "MEDIUM" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/catalog/datacenters/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "US-CA-2" } ], "get": { "operationId": "getDataCenter", "x-runpod-scope": "catalog:read", "summary": "Get a data center", "x-mint": { "metadata": { "description": "Retrieve a single Runpod data center by ID, optionally including current GPU or CPU availability for Pod deployment." } }, "description": "Returns a single data center. Availability is included only when requested with include=GPU_AVAILABILITY or include=CPU_AVAILABILITY.", "tags": [ "Catalog" ], "parameters": [ { "name": "include", "in": "query", "required": false, "description": "Comma-separated optional expansions. Supported value: GPU_AVAILABILITY, CPU_AVAILABILITY.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataCenterInclude" }, "example": [ "GPU_AVAILABILITY" ] } } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataCenter" }, "examples": { "dataCenter": { "summary": "Successful response", "value": { "id": "US-KS-2", "name": "US Kansas 2", "region": "NORTH_AMERICA", "globalNetwork": true, "networkVolumeTypes": [ "STANDARD", "HIGH_PERFORMANCE" ], "compliance": [ "SOC_2_TYPE_2", "ISO_IEC_27001" ], "gpuAvailability": [ { "id": "NVIDIA GeForce RTX 4090", "name": "RTX 4090", "availability": "HIGH" } ], "cpuAvailability": [ { "id": "cpu3c-2-4", "name": "Compute-Optimized", "availability": "MEDIUM" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/catalog/templates": { "get": { "operationId": "listPublicTemplates", "x-runpod-scope": "catalog:read", "summary": "List public templates", "x-mint": { "metadata": { "description": "List Runpod public templates by official, verified, or community source and inspect reusable Pod and Serverless configurations." } }, "description": "Returns the public template catalog. `source` selects which slice:\n`official` (the default) is Runpod-curated templates, `verified` is\ncommunity templates Runpod has verified, and `community` is everything\nelse other users have shared publicly. Both pod and serverless\ntemplates appear — use each entry's `serverless` flag to tell them\napart. `registry` is always null for templates you don't own. Your own\ntemplates (public or private) are managed under `/v2/templates`; fetch\nany individual template — catalog or owned — via `/v2/templates/{id}`.\n\nAt most 100 templates are returned. Cursor pagination is not yet\nsupported here; `pagination` is always the exhausted marker\n(`nextCursor: null`, `hasNextPage: false`).\n", "tags": [ "Catalog" ], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "official", "verified", "community" ], "default": "official" }, "description": "Which slice of the catalog to return: `official` for\nRunpod-curated templates (default), `verified` for\nRunpod-verified community templates, or `community` for all other\npublicly shared templates.\n", "example": "official" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" }, "examples": { "templates": { "summary": "Successful response", "value": { "templates": [ { "id": "30zmvf89kd", "name": "PyTorch 2.8", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 50, "mounts": {}, "ports": [ "8888/http", "22/tcp" ], "env": {}, "registry": null, "serverless": false, "public": true, "category": "NVIDIA", "startSsh": true, "startJupyter": true, "allowedCudaVersions": [] } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/catalog/templates/{id}/readme": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "30zmvf89kd" } ], "get": { "operationId": "getPublicTemplateReadme", "x-runpod-scope": "catalog:read", "summary": "Get a public template README", "x-mint": { "metadata": { "description": "Retrieve the Markdown README of a public Runpod template, with setup and usage instructions." } }, "description": "Returns the README of a public catalog template as raw Markdown.\nOnly public templates are served. Returns `404` when the template does\nnot exist, is not public, or has no README. Use\n`GET /v2/templates/{id}/readme` for your private templates.\n", "tags": [ "Catalog" ], "responses": { "200": { "$ref": "#/components/responses/TemplateReadme" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/cost-centers": { "get": { "operationId": "listCostCenters", "x-runpod-scope": "billing:read", "summary": "List cost centers", "x-mint": { "metadata": { "description": "List the Runpod cost centers available to the authenticated user for attributing resource spend in billing." } }, "description": "Returns the caller's cost centers, cursor-paginated newest-first; an\nomitted `limit` defaults to 1000. Follow `pagination.nextCursor` until\n`hasNextPage` is false.\n", "tags": [ "Cost Centers" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match against `value`.", "schema": { "type": "string", "minLength": 1 }, "example": "team" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCostCentersResponse" }, "examples": { "costCenters": { "summary": "Successful response", "value": { "costCenters": [ { "id": "clz1x9k4a0000qw3h8s7d2f1g", "value": "team-ml" } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createCostCenter", "x-runpod-scope": "billing:write", "summary": "Create a cost center", "x-mint": { "metadata": { "description": "Create a Runpod cost center and optionally attribute pods, clusters, serverless endpoints, and network volumes to it." } }, "description": "Creates a cost center — a named label that groups resource spend so it can be broken out in billing. Pass `resources` to attribute resources at creation time; attaching is all-or-nothing, and a resource that already belongs to another cost center is rejected rather than moved.", "tags": [ "Cost Centers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCostCenterRequest" }, "examples": { "bare": { "summary": "Name only", "value": { "value": "team-ml" } }, "withResources": { "summary": "With resources attributed", "value": { "value": "team-ml", "resources": [ { "id": "p9k2m4n6q8", "type": "POD" }, { "id": "nv_7h3x1q", "type": "NETWORK_VOLUME" } ] } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostCenter" }, "examples": { "costCenter": { "summary": "Successful response", "value": { "id": "clz1x9k4a0000qw3h8s7d2f1g", "value": "team-ml" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "A resource is already attributed to another cost center, or the account's plan does not allow more cost centers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/cost-centers/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Cost center identifier." } ], "get": { "operationId": "getCostCenter", "x-runpod-scope": "billing:read", "summary": "Get a cost center", "x-mint": { "metadata": { "description": "Retrieve a Runpod cost center by ID." } }, "description": "Returns one cost center. Its attributed resources are listed by\n`GET /v2/cost-centers/{id}/resources`. Returns 404 when the cost center\ndoes not exist or is not the caller's.\n", "tags": [ "Cost Centers" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostCenter" }, "examples": { "costCenter": { "summary": "Successful response", "value": { "id": "clz1x9k4a0000qw3h8s7d2f1g", "value": "team-ml" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateCostCenter", "x-runpod-scope": "billing:write", "summary": "Rename a cost center", "x-mint": { "metadata": { "description": "Rename a Runpod cost center. Resources already attributed to it follow the new name automatically." } }, "description": "Renames a cost center. Resources attributed to it are unaffected and\nfollow the new name — the attribution is by identifier, not by name.\n", "tags": [ "Cost Centers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCostCenterRequest" }, "examples": { "rename": { "summary": "Rename", "value": { "value": "team-ml-eu" } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostCenter" }, "examples": { "costCenter": { "summary": "Successful response", "value": { "id": "clz1x9k4a0000qw3h8s7d2f1g", "value": "team-ml-eu" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteCostCenter", "x-runpod-scope": "billing:write", "summary": "Delete a cost center", "x-mint": { "metadata": { "description": "Delete a Runpod cost center. Fails while any resource is still attributed to it." } }, "description": "Deletes a cost center. The delete fails with 409 while any resource is\nstill attributed to the cost center; detach those resources first.\n", "tags": [ "Cost Centers" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Resources are still attributed to the cost center. The detail lists each as `{resourceType}/{resourceId}`, ready for the detach route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/cost-centers/{id}/resources": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Cost center identifier." } ], "get": { "operationId": "listCostCenterResources", "x-runpod-scope": "billing:read", "summary": "List a cost center's resources", "x-mint": { "metadata": { "description": "List the Runpod pods, clusters, serverless endpoints, and network volumes attributed to a cost center." } }, "description": "Returns the resources attributed to one cost center, cursor-paginated;\nan omitted `limit` defaults to 1000. Each entry is the `{type}/{id}`\npair `DELETE /v2/cost-centers/{id}/{resourceType}/{resourceId}` takes.\nA cost center with nothing attributed returns an empty list; one that\ndoes not exist or is not the caller's returns 404.\n", "tags": [ "Cost Centers" ], "parameters": [ { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCostCenterResourcesResponse" }, "examples": { "resources": { "summary": "Successful response", "value": { "resources": [ { "id": "p9k2m4n6q8", "type": "POD" }, { "id": "nv_7h3x1q", "type": "NETWORK_VOLUME" } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/cost-centers/{id}/{resourceType}/{resourceId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Cost center identifier." }, { "name": "resourceType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceType" }, "description": "Kind of resource." }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Resource identifier." } ], "put": { "operationId": "attachCostCenterResource", "x-runpod-scope": "billing:write", "summary": "Attribute a resource to a cost center", "x-mint": { "metadata": { "description": "Attribute a Runpod pod, cluster, serverless endpoint, or network volume to a cost center." } }, "description": "Attributes a resource to a cost center. Repeating the request is a\nno-op. A resource belongs to at most one cost center; one already\nattributed elsewhere is rejected with 409 rather than moved.\n", "tags": [ "Cost Centers" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Attributed. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "The resource is already attributed to a different cost center.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "detachCostCenterResource", "x-runpod-scope": "billing:write", "summary": "Remove a resource from a cost center", "x-mint": { "metadata": { "description": "Remove a Runpod pod, cluster, serverless endpoint, or network volume from a cost center." } }, "description": "Removes a resource's attribution to a cost center. The resource itself\nis untouched. Returns 404 when the cost center does not exist or the\nresource is not attributed to it, so repeating a DELETE that succeeded\nreturns 404.\n", "tags": [ "Cost Centers" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Removed. Response has no body." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/tags": { "get": { "operationId": "listTags", "x-runpod-scope": "tags:read", "summary": "List tags", "x-mint": { "metadata": { "description": "List the Runpod tags available to the authenticated user." } }, "description": "Returns the caller's tags, newest first, cursor-paginated. Tags under\nthe reserved `runpod:` prefix, such as cost centers, are never listed.\nFollow `pagination.nextCursor` until `hasNextPage` is false.\n", "tags": [ "Tags" ], "parameters": [ { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTagsResponse" }, "examples": { "tags": { "summary": "Successful response", "value": { "tags": [ { "id": "clz1x9k4a0000qw3h8s7d2f1g", "key": "env", "value": "dev", "createdAt": "2026-11-04T09:00:00Z", "updatedAt": "2026-11-04T09:00:00Z" } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createTag", "x-runpod-scope": "tags:write", "summary": "Create a tag", "x-mint": { "metadata": { "description": "Create a Runpod tag and optionally attach it to pods, clusters, serverless endpoints, and network volumes." } }, "description": "Creates a tag. Pass `resources` to attach it at creation time; the tag is created and attached in one step, so if any resource cannot be attached, no tag is created.", "tags": [ "Tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagRequest" }, "examples": { "bare": { "summary": "Key and value only", "value": { "key": "env", "value": "dev" } }, "withResources": { "summary": "With resources attached", "value": { "key": "env", "value": "dev", "resources": [ { "id": "p9k2m4n6q8", "type": "POD" }, { "id": "nv_7h3x1q", "type": "NETWORK_VOLUME" } ] } } } } } }, "responses": { "201": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" }, "examples": { "tag": { "summary": "Successful response", "value": { "id": "clz1x9k4a0000qw3h8s7d2f1g", "key": "env", "value": "dev", "createdAt": "2026-11-04T09:00:00Z", "updatedAt": "2026-11-04T09:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "A tag with this key and value already exists, or a resource already carries 25 public tags, the most one resource can carry. In the second case the detail names the resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/tags/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Tag identifier." } ], "get": { "operationId": "getTag", "x-runpod-scope": "tags:read", "summary": "Get a tag", "x-mint": { "metadata": { "description": "Retrieve a Runpod tag by ID." } }, "description": "Returns one tag. Its ID stays the same when the key or value changes. Returns 404 when the tag does not exist, is deleted, is not the caller's, or is reserved: a cost center ID is a reserved tag, so read it through `GET /v2/cost-centers/{id}`.", "tags": [ "Tags" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" }, "examples": { "tag": { "summary": "Successful response", "value": { "id": "clz1x9k4a0000qw3h8s7d2f1g", "key": "env", "value": "dev", "createdAt": "2026-11-04T09:00:00Z", "updatedAt": "2026-11-04T09:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateTag", "x-runpod-scope": "tags:write", "summary": "Update a tag", "x-mint": { "metadata": { "description": "Change the key or value of a Runpod tag. Resources it is attached to keep it." } }, "description": "Changes a tag's key, value, or both. The tag keeps its ID and stays attached to the same resources. Returns 404 when the tag does not exist or is not the caller's.", "tags": [ "Tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagRequest" }, "examples": { "value": { "summary": "Change the value", "value": { "value": "prod" } }, "keyAndValue": { "summary": "Change the key and value", "value": { "key": "environment", "value": "prod" } } } } } }, "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" }, "examples": { "tag": { "summary": "Successful response", "value": { "id": "clz1x9k4a0000qw3h8s7d2f1g", "key": "environment", "value": "prod", "createdAt": "2026-11-04T09:00:00Z", "updatedAt": "2026-11-04T09:30:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Another tag already has this key and value.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteTag", "x-runpod-scope": "tags:write", "summary": "Delete a tag", "x-mint": { "metadata": { "description": "Delete a Runpod tag and remove it from every resource it is attached to." } }, "description": "Deletes a tag and removes it from every resource it is attached to. The resources themselves are unchanged, and nothing needs to be detached first. Returns 404 when the tag does not exist, is already deleted, is not the caller's, or is reserved: a cost center ID is a reserved tag, so delete it through `DELETE /v2/cost-centers/{id}`.", "tags": [ "Tags" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Deleted. Response has no body." }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/tags/{id}/resources": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Tag identifier." } ], "get": { "operationId": "listTagResources", "x-runpod-scope": "tags:read", "summary": "List a tag's resources", "x-mint": { "metadata": { "description": "List the Runpod pods, clusters, serverless endpoints, and network volumes a tag is attached to." } }, "description": "Returns the resources a tag is attached to, newest attachment first,\ncursor-paginated. Each entry is the `{type}/{id}` pair\n`/v2/tags/{id}/resources/{resourceType}/{resourceId}` takes. A tag\nattached to nothing returns an empty list; one that does not exist, is\ndeleted, is not the caller's, or is reserved returns 404.\n", "tags": [ "Tags" ], "parameters": [ { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTagResourcesResponse" }, "examples": { "resources": { "summary": "Successful response", "value": { "resources": [ { "id": "p9k2m4n6q8", "type": "POD" }, { "id": "nv_7h3x1q", "type": "NETWORK_VOLUME" } ], "pagination": { "nextCursor": null, "hasNextPage": false } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/tags/{id}/resources/{resourceType}/{resourceId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Tag identifier." }, { "name": "resourceType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceType" }, "description": "Kind of resource." }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Resource identifier." } ], "put": { "operationId": "attachTagResource", "x-runpod-scope": "tags:write", "summary": "Attach a tag to a resource", "x-mint": { "metadata": { "description": "Attach a Runpod tag to a pod, cluster, serverless endpoint, or network volume." } }, "description": "Attaches a tag to a resource. Repeating the request is a no-op. A resource can carry several tags. Returns 404 when the tag or the resource does not exist or is not the caller's; the detail names a missing resource as `{resourceType}/{resourceId}`.", "tags": [ "Tags" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Attached. Response has no body." }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "The resource already carries 25 public tags, the most one resource can carry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "$ref": "#/components/responses/RequestTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "detachTagResource", "x-runpod-scope": "tags:write", "summary": "Remove a tag from a resource", "x-mint": { "metadata": { "description": "Remove a Runpod tag from a pod, cluster, serverless endpoint, or network volume." } }, "description": "Removes a tag from one resource. The tag, the resource and the tag's other attachments are untouched. Returns 404 when the tag does not exist, is not the caller's, or is reserved (a cost center); when the resource does not carry it, so repeating a DELETE that succeeded returns 404; or when the resource is not the caller's to change. The detail names that last resource as `{resourceType}/{resourceId}`.", "tags": [ "Tags" ], "responses": { "204": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Removed. Response has no body." }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/audit-logs": { "get": { "operationId": "listAuditLogs", "x-runpod-scope": "audit:read", "summary": "List audit logs", "x-mint": { "metadata": { "description": "List your Runpod audit trail to see who acted on each resource, with filters for actor, action, time range, and text, newest first." } }, "description": "Returns the account's audit trail, newest first, cursor-paginated; an omitted `limit` defaults to 200. Each entry records who acted (`actorId`, `email`), what they did (`action`), to which resource (`resourceType`, `resourceId`), and the details of the change (`value`). When the caller belongs to an organization the trail is the organization's, and `actorIds` narrows it to specific members; otherwise it is the trail of the account the request acts for. Filters combine with AND. Entries older than the account's audit log retention window are not returned, and an account whose plan does not include audit logs is answered 403. Follow `pagination.nextCursor` until `hasNextPage` is false.", "tags": [ "Audit Logs" ], "parameters": [ { "$ref": "#/components/parameters/AuditLogActorIdsFilter" }, { "$ref": "#/components/parameters/AuditLogActionsFilter" }, { "$ref": "#/components/parameters/AuditLogStartTime" }, { "$ref": "#/components/parameters/AuditLogEndTime" }, { "$ref": "#/components/parameters/AuditLogSearch" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "$ref": "#/components/parameters/PaginationLimitAuditLogs" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditLogsResponse" }, "examples": { "auditLogs": { "summary": "Successful response", "value": { "auditLogs": [ { "actorId": "user_id_abc_123", "email": "actor@example.com", "resourceType": "pod", "resourceId": "abc123", "action": "delete", "value": "{\"status\":\"TERMINATED\"}", "timestamp": "2026-09-02T00:00:00Z" }, { "actorId": "user_id_abc_123", "email": "actor@example.com", "resourceType": "pod", "resourceId": "abc123", "action": "rename", "value": "{\"name\":\"training-run-7\"}", "timestamp": "2026-09-01T18:30:00Z" }, { "actorId": "user_id_def_456", "email": "admin@example.com", "resourceType": "secret", "resourceId": "sec_789", "action": "update", "value": "{\"id\":\"sec_789\",\"name\":\"HF_TOKEN\",\"sharedWithOrganization\":true}", "timestamp": "2026-09-01T09:15:00Z" } ], "pagination": { "nextCursor": "eyJ0cyI6IjIwMjYtMDktMDFUMDk6MTU6MDBaIn0=", "hasNextPage": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "413": { "$ref": "#/components/responses/ResponseTooLargeError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/billing/balance": { "get": { "operationId": "getBalance", "x-runpod-scope": "billing:read", "summary": "Get the account balance", "x-mint": { "metadata": { "description": "Read your Runpod account balance and billing mode before you deploy." } }, "description": "Returns the balance of the account this request acts for: your own account, the team selected for the request, or your organization. An organization with no billing account answers 404.", "tags": [ "Billing" ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "examples": { "prepaid": { "summary": "Prepaid account", "value": { "balanceAmount": 42.18, "billingMode": "PREPAID" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/billing": { "get": { "operationId": "listBilling", "x-runpod-scope": "billing:read", "summary": "Get aggregated billing history", "x-mint": { "metadata": { "description": "Retrieve time-bucketed total Runpod spend across Pods, Serverless, storage, Public Endpoints, and Clusters for the authenticated account." } }, "description": "Returns time-bucketed total spend across all billable Runpod resources for the authenticated user. Use startTime/endTime with bucketSize for an explicit range, or lastN with bucketSize for the most recent buckets. Each record reports one bucket's total plus pod, serverless, storage, public endpoint, and Instant Cluster cost components. The metadata block echoes the resolved query window, record count, and totals across all returned buckets.\n", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/BillingStartTime" }, { "$ref": "#/components/parameters/BillingEndTime" }, { "$ref": "#/components/parameters/BillingBucketSize" }, { "$ref": "#/components/parameters/BillingLastN" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBillingResponse" }, "examples": { "billing": { "summary": "Successful response", "value": { "records": [ { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "totalAmount": 42.34, "podGpuAmount": 18.2, "podCpuAmount": 0, "podDiskAmount": 1.1, "serverlessGpuAmount": 13.85, "serverlessCpuAmount": 0, "serverlessDiskAmount": 0.44, "serverlessFeeAmount": 0, "storageStandardAmount": 0, "storageHighPerformanceAmount": 2.5, "endpointAmount": 3.21, "clusterGpuAmount": 2.5, "clusterDiskAmount": 0.3, "clusterNetworkingAmount": 0.24 } ], "metadata": { "query": { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "bucketSize": "day" }, "recordCount": 1, "totals": { "totalAmount": 42.34, "podGpuAmount": 18.2, "podCpuAmount": 0, "podDiskAmount": 1.1, "serverlessGpuAmount": 13.85, "serverlessCpuAmount": 0, "serverlessDiskAmount": 0.44, "serverlessFeeAmount": 0, "storageStandardAmount": 0, "storageHighPerformanceAmount": 2.5, "endpointAmount": 3.21, "clusterGpuAmount": 2.5, "clusterDiskAmount": 0.3, "clusterNetworkingAmount": 0.24 } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/billing/pods": { "get": { "operationId": "listPodBilling", "x-runpod-scope": "billing:read", "summary": "Get pod billing history", "x-mint": { "metadata": { "description": "Retrieve time-bucketed billing details for one or all Runpod Pods, including GPU, CPU, disk, total costs, and query metadata." } }, "description": "Returns pod-only billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use podId to narrow the response to one GPU or CPU pod; without it, records are emitted per pod per bucket. Each record includes podId, GPU, CPU, disk, and total amounts, while metadata echoes the resolved query and totals across the pod records. Use listBilling when you need aggregate spend across every billable resource family.\n", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/BillingStartTime" }, { "$ref": "#/components/parameters/BillingEndTime" }, { "$ref": "#/components/parameters/BillingBucketSize" }, { "$ref": "#/components/parameters/BillingLastN" }, { "name": "podId", "in": "query", "required": false, "description": "Filter to a specific pod (GPU or CPU).", "schema": { "type": "string" }, "example": "pod_abc123" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPodBillingResponse" }, "examples": { "podBilling": { "summary": "Successful response", "value": { "records": [ { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "podId": "7h9k2m4n6p", "totalAmount": 12.34, "gpuAmount": 11.1, "cpuAmount": 0, "diskAmount": 1.24 } ], "metadata": { "query": { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "bucketSize": "day", "podId": "7h9k2m4n6p" }, "recordCount": 1, "totals": { "totalAmount": 12.34, "gpuAmount": 11.1, "cpuAmount": 0, "diskAmount": 1.24 }, "uniquePodCount": 1 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/billing/serverless": { "get": { "operationId": "listServerlessBilling", "x-runpod-scope": "billing:read", "summary": "Get serverless billing history", "x-mint": { "metadata": { "description": "Retrieve time-bucketed billing history for one or all Runpod Serverless endpoints, including compute, disk, platform, and total costs." } }, "description": "Returns serverless endpoint billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use serverlessId to filter to one endpoint; without it, records are emitted per serverless endpoint per bucket. Each record reports endpoint-level GPU, CPU, disk, and total amounts. This is distinct from pod billing, which covers standalone GPU and CPU pod costs rather than serverless endpoint workloads.\n", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/BillingStartTime" }, { "$ref": "#/components/parameters/BillingEndTime" }, { "$ref": "#/components/parameters/BillingBucketSize" }, { "$ref": "#/components/parameters/BillingLastN" }, { "name": "serverlessId", "in": "query", "required": false, "description": "Filter to a specific serverless endpoint.", "schema": { "type": "string" }, "example": "jpnw0v75y3qoql" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListServerlessBillingResponse" }, "examples": { "serverlessBilling": { "summary": "Successful response", "value": { "records": [ { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "serverlessId": "4m7x2k9q", "totalAmount": 8.9, "gpuAmount": 8.5, "cpuAmount": 0, "diskAmount": 0.4, "feeAmount": 0 } ], "metadata": { "query": { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "bucketSize": "day", "serverlessId": "4m7x2k9q" }, "recordCount": 1, "totals": { "totalAmount": 8.9, "gpuAmount": 8.5, "cpuAmount": 0, "diskAmount": 0.4, "feeAmount": 0 }, "uniqueServerlessCount": 1 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/billing/endpoints": { "get": { "operationId": "listEndpointBilling", "x-runpod-scope": "billing:read", "summary": "Get public endpoint billing history", "x-mint": { "metadata": { "description": "Retrieve time-bucketed billing history for Runpod Public Endpoints, including endpoint totals and resolved query metadata." } }, "description": "Returns Runpod public endpoint billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Each record reports the endpoint total for one bucket, and metadata echoes the resolved query window, record count, and total endpoint amount across all returned records.\n", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/BillingStartTime" }, { "$ref": "#/components/parameters/BillingEndTime" }, { "$ref": "#/components/parameters/BillingBucketSize" }, { "$ref": "#/components/parameters/BillingLastN" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointBillingResponse" }, "examples": { "endpointBilling": { "summary": "Successful response", "value": { "records": [ { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "totalAmount": 3.21 } ], "metadata": { "query": { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "bucketSize": "day" }, "recordCount": 1, "totals": { "totalAmount": 3.21 } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/billing/network-volumes": { "get": { "operationId": "listNetworkVolumeBilling", "x-runpod-scope": "billing:read", "summary": "Get network volume billing history", "x-mint": { "metadata": { "description": "Retrieve time-bucketed billing history for one or all Runpod network volumes, including storage tiers, totals, and query metadata." } }, "description": "Returns network volume billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use networkVolumeId to filter to one volume; without it, records are emitted per volume per bucket. Each record includes standard storage, high-performance storage, and total amounts, while metadata reports the resolved query, distinct volume count, and totals across the returned records.\n", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/BillingStartTime" }, { "$ref": "#/components/parameters/BillingEndTime" }, { "$ref": "#/components/parameters/BillingBucketSize" }, { "$ref": "#/components/parameters/BillingLastN" }, { "name": "networkVolumeId", "in": "query", "required": false, "description": "Filter to a specific network volume.", "schema": { "type": "string" }, "example": "vol_abc123" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNetworkVolumeBillingResponse" }, "examples": { "networkVolumeBilling": { "summary": "Successful response", "value": { "records": [ { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "networkVolumeId": "2q9m7x4c", "totalAmount": 5.79, "standardAmount": 0, "highPerformanceAmount": 5.79 } ], "metadata": { "query": { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "bucketSize": "day", "networkVolumeId": "2q9m7x4c" }, "recordCount": 1, "totals": { "totalAmount": 5.79, "standardAmount": 0, "highPerformanceAmount": 5.79 }, "uniqueNetworkVolumeCount": 1 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/billing/clusters": { "get": { "operationId": "listClusterBilling", "x-runpod-scope": "billing:read", "summary": "Get cluster billing history", "x-mint": { "metadata": { "description": "Retrieve time-bucketed Runpod Cluster billing history, including GPU compute, disk, inter-node networking, and total costs." } }, "description": "Returns Cluster billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use clusterId to filter to one cluster; without it, records are emitted per cluster per bucket. Each record includes GPU compute, disk, inter-node networking, and total amounts. Clusters are GPU-only, so no CPU cost component is returned.\n", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/BillingStartTime" }, { "$ref": "#/components/parameters/BillingEndTime" }, { "$ref": "#/components/parameters/BillingBucketSize" }, { "$ref": "#/components/parameters/BillingLastN" }, { "name": "clusterId", "in": "query", "required": false, "description": "Filter to a specific cluster.", "schema": { "type": "string" }, "example": "cluster_abc123" } ], "responses": { "200": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClusterBillingResponse" }, "examples": { "clusterBilling": { "summary": "Successful response", "value": { "records": [ { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "clusterId": "5c2n8m4q", "totalAmount": 99.0, "gpuAmount": 95.0, "diskAmount": 3.0, "networkingAmount": 1.0 } ], "metadata": { "query": { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-02T00:00:00Z", "bucketSize": "day", "clusterId": "5c2n8m4q" }, "recordCount": 1, "totals": { "totalAmount": 99.0, "gpuAmount": 95.0, "diskAmount": 3.0, "networkingAmount": 1.0 }, "uniqueClusterCount": 1 } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "default": { "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } } }