--- title: "Instance data model" url: "https://docs.unified.to/compute/instance/model" description: "The Instance data model object in Unified's Instance API: 40 fields, including created_at, updated_at and name, with types and enum values." --- # Instance data model View field support, webhooks, and list parameters for each integration on the [Supported Integrations](https://docs.unified.to/compute/integrations.md) page. | Field | Type | Required | Description | | -------------------------------- | ---------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | No | Unique identifier for the instance | | created\_at | string (date-time) | No | When the instance was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | updated\_at | string (date-time) | No | When the instance was last updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | name | string | No | Display name of the instance | | type | enum | No | The kind of compute unit Values: CONTAINER, VM, BAREMETAL, SANDBOX, OTHER | | status | enum | No | Normalized lifecycle status; set on update to start, stop, pause, resume, restart or terminate Values: PROVISIONING, STARTING, RUNNING, STOPPING, STOPPED, PAUSING, PAUSED, RESUMING, RESTARTING, TERMINATING, TERMINATED, PREEMPTED, ERROR, OTHER | | status\_reason | string | No | Vendor explanation of the current status (eg. shutdown or failure reason) | | allowed\_actions | enum | No | Lifecycle actions the vendor currently allows Values: START, STOP, RESTART, PAUSE, RESUME, TERMINATE | | market | enum | No | Pricing market the instance runs in Values: ON\_DEMAND, SPOT, RESERVED, COMMUNITY, OTHER | | region\_id | string | No | The region the instance runs in | | template\_id | string | No | The template the instance was created from | | image | string | No | Container or OS image, when not created from a template | | source\_snapshot\_id | string | No | The snapshot the instance was restored or forked from | | parent\_instance\_id | string | No | The instance this one was forked from | | gputype\_id | string | No | The GPU or instance type of this instance | | gpu\_model | enum | No | Normalized GPU model Values: NVIDIA\_GB300, NVIDIA\_B300, NVIDIA\_GB200, NVIDIA\_B200, NVIDIA\_GH200, NVIDIA\_H200, NVIDIA\_H100\_SXM, NVIDIA\_H100\_PCIE, NVIDIA\_H100\_NVL, NVIDIA\_A100\_SXM\_80GB, NVIDIA\_A100\_PCIE\_80GB, NVIDIA\_A100\_40GB, NVIDIA\_L40S, NVIDIA\_L40, NVIDIA\_L4, NVIDIA\_A40, NVIDIA\_A10, NVIDIA\_RTX\_PRO\_6000, NVIDIA\_RTX\_6000\_ADA, NVIDIA\_RTX\_A6000, NVIDIA\_RTX\_A5000, NVIDIA\_RTX\_A4000, NVIDIA\_RTX\_5090, NVIDIA\_RTX\_4090, NVIDIA\_RTX\_3090, NVIDIA\_V100, NVIDIA\_T4, AMD\_MI355X, AMD\_MI325X, AMD\_MI300X, AMD\_MI250, OTHER | | gpu\_count | number | No | Number of GPUs attached (0 for CPU-only) | | sku | string | No | The vendor's own SKU or size name | | cpu\_count | number | No | Number of vCPUs; may be fractional | | memory\_mb | number | No | System memory in MiB | | disk\_mb | number | No | Disk size in MiB | | architecture | enum | No | CPU architecture Values: X86\_64, ARM64, OTHER | | price\_amount | number | No | List price for the instance | | price\_unit | enum | No | Unit that price\_amount is quoted in Values: PER\_GPU\_HOUR, PER\_INSTANCE\_HOUR, OTHER | | currency | string | No | Currency of price\_amount (ISO 4217) | | volume\_ids | string\[\] | No | Volumes mounted on the instance | | endpoints | [ComputeEndpoint](https://docs.unified.to/compute/instance/model.md#ComputeEndpoint)\[\] | No | Exposed ports and their URLs | | endpoints\[\].port | number | No | The port inside the instance | | endpoints\[\].protocol | enum | No | The protocol served on this port Values: HTTP, HTTPS, TCP, UDP, OTHER | | endpoints\[\].url | string | No | Public or proxied URL for this port | | endpoints\[\].is\_auth\_required | boolean | No | Whether the URL requires a vendor access token | | ssh | object | No | SSH connection details | | ssh.host | string | No | SSH host | | ssh.port | number | No | SSH port | | ssh.username | string | No | SSH username | | has\_internet\_access | boolean | No | Whether outbound network access is allowed | | timeout\_seconds | number | No | Seconds until the instance expires; set on update to extend it | | expires\_at | string (date-time) | No | When the instance will expire (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | on\_expire | enum | No | What happens when the instance expires Values: TERMINATE, PAUSE, STOP, OTHER | | idle\_timeout\_seconds | number | No | Seconds of inactivity before on\_idle applies | | on\_idle | enum | No | What happens when the instance is idle Values: TERMINATE, PAUSE, STOP, OTHER | | project\_identifier | string | No | Vendor project, team or app that groups the instance (reference to TaskProject) | | service\_id | string | No | The service (app) this instance runs for, on hosting platforms | | env | [ComputeEnv](https://docs.unified.to/compute/instance/model.md#ComputeEnv)\[\] | No | Environment variables (write-only values) | | env\[\].name | string | Yes | Environment variable name | | env\[\].value | string | No | Environment variable value (write-only; never returned) | | started\_at | string (date-time) | No | When the instance last started (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | terminated\_at | string (date-time) | No | When the instance was terminated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | metadata | [ComputeMetadata](https://docs.unified.to/compute/instance/model.md#ComputeMetadata)\[\] | No | Vendor labels, tags and metadata | | metadata\[\].id | string | No | | | metadata\[\].slug | string | No | The label, tag or metadata key | | metadata\[\].value | object | No | The label, tag or metadata value | | metadata\[\].namespace | string | No | The origin of the value (eg. labels, tags, metadata) | | metadata\[\].format | enum | No | The data type of the value Values: TEXT, NUMBER, DATE, BOOLEAN, ARRAY, OBJECT | | metadata\[\].extra\_data | object | No | | ## TypeScript ```typescript export type ComputeInstance = { id?: string; // Unique identifier for the instance created_at?: string-time; // When the instance was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) updated_at?: string-time; // When the instance was last updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) name?: string; // Display name of the instance type?: 'CONTAINER' | 'VM' | 'BAREMETAL' | 'SANDBOX' | 'OTHER'; // The kind of compute unit status?: 'PROVISIONING' | 'STARTING' | 'RUNNING' | 'STOPPING' | 'STOPPED' | 'PAUSING' | 'PAUSED' | 'RESUMING' | 'RESTARTING' | 'TERMINATING' | 'TERMINATED' | 'PREEMPTED' | 'ERROR' | 'OTHER'; // Normalized lifecycle status; set on update to start, stop, pause, resume, restart or terminate status_reason?: string; // Vendor explanation of the current status (eg. shutdown or failure reason) allowed_actions?: ( 'START' | 'STOP' | 'RESTART' | 'PAUSE' | 'RESUME' | 'TERMINATE' )[]; // Lifecycle actions the vendor currently allows market?: 'ON_DEMAND' | 'SPOT' | 'RESERVED' | 'COMMUNITY' | 'OTHER'; // Pricing market the instance runs in region_id?: string; // The region the instance runs in template_id?: string; // The template the instance was created from image?: string; // Container or OS image, when not created from a template source_snapshot_id?: string; // The snapshot the instance was restored or forked from parent_instance_id?: string; // The instance this one was forked from gputype_id?: string; // The GPU or instance type of this instance gpu_model?: 'NVIDIA_GB300' | 'NVIDIA_B300' | 'NVIDIA_GB200' | 'NVIDIA_B200' | 'NVIDIA_GH200' | 'NVIDIA_H200' | 'NVIDIA_H100_SXM' | 'NVIDIA_H100_PCIE' | 'NVIDIA_H100_NVL' | 'NVIDIA_A100_SXM_80GB' | 'NVIDIA_A100_PCIE_80GB' | 'NVIDIA_A100_40GB' | 'NVIDIA_L40S' | 'NVIDIA_L40' | 'NVIDIA_L4' | 'NVIDIA_A40' | 'NVIDIA_A10' | 'NVIDIA_RTX_PRO_6000' | 'NVIDIA_RTX_6000_ADA' | 'NVIDIA_RTX_A6000' | 'NVIDIA_RTX_A5000' | 'NVIDIA_RTX_A4000' | 'NVIDIA_RTX_5090' | 'NVIDIA_RTX_4090' | 'NVIDIA_RTX_3090' | 'NVIDIA_V100' | 'NVIDIA_T4' | 'AMD_MI355X' | 'AMD_MI325X' | 'AMD_MI300X' | 'AMD_MI250' | 'OTHER'; // Normalized GPU model gpu_count?: number; // Number of GPUs attached (0 for CPU-only) sku?: string; // The vendor's own SKU or size name cpu_count?: number; // Number of vCPUs; may be fractional memory_mb?: number; // System memory in MiB disk_mb?: number; // Disk size in MiB architecture?: 'X86_64' | 'ARM64' | 'OTHER'; // CPU architecture price_amount?: number; // List price for the instance price_unit?: 'PER_GPU_HOUR' | 'PER_INSTANCE_HOUR' | 'OTHER'; // Unit that price_amount is quoted in currency?: string; // Currency of price_amount (ISO 4217) volume_ids?: string[]; // Volumes mounted on the instance endpoints?: []; // Exposed ports and their URLs ssh?: { host?: string; // SSH host port?: number; // SSH port username?: string; // SSH username }; // SSH connection details has_internet_access?: boolean; // Whether outbound network access is allowed timeout_seconds?: number; // Seconds until the instance expires; set on update to extend it expires_at?: string-time; // When the instance will expire (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) on_expire?: 'TERMINATE' | 'PAUSE' | 'STOP' | 'OTHER'; // What happens when the instance expires idle_timeout_seconds?: number; // Seconds of inactivity before on_idle applies on_idle?: 'TERMINATE' | 'PAUSE' | 'STOP' | 'OTHER'; // What happens when the instance is idle project_identifier?: string; // Vendor project, team or app that groups the instance (reference to TaskProject) service_id?: string; // The service (app) this instance runs for, on hosting platforms env?: []; // Environment variables (write-only values) started_at?: string-time; // When the instance last started (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) terminated_at?: string-time; // When the instance was terminated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) metadata?: []; // Vendor labels, tags and metadata raw?: any; // Raw data from integration } ``` ## Zod ```typescript import { z } from 'zod'; export const ZodComputeInstance = z.object({ id: z.string().optional().describe("Unique identifier for the instance"), created_at: z.string-time().optional().describe("When the instance was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), updated_at: z.string-time().optional().describe("When the instance was last updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), name: z.string().optional().describe("Display name of the instance"), type: z.enum("CONTAINER", "VM", "BAREMETAL", "SANDBOX", "OTHER").optional().describe("The kind of compute unit"), status: z.enum("PROVISIONING", "STARTING", "RUNNING", "STOPPING", "STOPPED", "PAUSING", "PAUSED", "RESUMING", "RESTARTING", "TERMINATING", "TERMINATED", "PREEMPTED", "ERROR", "OTHER").optional().describe("Normalized lifecycle status; set on update to start, stop, pause, resume, restart or terminate"), status_reason: z.string().optional().describe("Vendor explanation of the current status (eg. shutdown or failure reason)"), allowed_actions: z( 'START' | 'STOP' | 'RESTART' | 'PAUSE' | 'RESUME' | 'TERMINATE' ).optional().describe("Lifecycle actions the vendor currently allows"), market: z.enum("ON_DEMAND", "SPOT", "RESERVED", "COMMUNITY", "OTHER").optional().describe("Pricing market the instance runs in"), region_id: z.string().optional().describe("The region the instance runs in"), template_id: z.string().optional().describe("The template the instance was created from"), image: z.string().optional().describe("Container or OS image, when not created from a template"), source_snapshot_id: z.string().optional().describe("The snapshot the instance was restored or forked from"), parent_instance_id: z.string().optional().describe("The instance this one was forked from"), gputype_id: z.string().optional().describe("The GPU or instance type of this instance"), gpu_model: z.enum("NVIDIA_GB300", "NVIDIA_B300", "NVIDIA_GB200", "NVIDIA_B200", "NVIDIA_GH200", "NVIDIA_H200", "NVIDIA_H100_SXM", "NVIDIA_H100_PCIE", "NVIDIA_H100_NVL", "NVIDIA_A100_SXM_80GB", "NVIDIA_A100_PCIE_80GB", "NVIDIA_A100_40GB", "NVIDIA_L40S", "NVIDIA_L40", "NVIDIA_L4", "NVIDIA_A40", "NVIDIA_A10", "NVIDIA_RTX_PRO_6000", "NVIDIA_RTX_6000_ADA", "NVIDIA_RTX_A6000", "NVIDIA_RTX_A5000", "NVIDIA_RTX_A4000", "NVIDIA_RTX_5090", "NVIDIA_RTX_4090", "NVIDIA_RTX_3090", "NVIDIA_V100", "NVIDIA_T4", "AMD_MI355X", "AMD_MI325X", "AMD_MI300X", "AMD_MI250", "OTHER").optional().describe("Normalized GPU model"), gpu_count: z.number().optional().describe("Number of GPUs attached (0 for CPU-only)"), sku: z.string().optional().describe("The vendor's own SKU or size name"), cpu_count: z.number().optional().describe("Number of vCPUs; may be fractional"), memory_mb: z.number().optional().describe("System memory in MiB"), disk_mb: z.number().optional().describe("Disk size in MiB"), architecture: z.enum("X86_64", "ARM64", "OTHER").optional().describe("CPU architecture"), price_amount: z.number().optional().describe("List price for the instance"), price_unit: z.enum("PER_GPU_HOUR", "PER_INSTANCE_HOUR", "OTHER").optional().describe("Unit that price_amount is quoted in"), currency: z.string().optional().describe("Currency of price_amount (ISO 4217)"), volume_ids: z.array().optional().describe("Volumes mounted on the instance"), endpoints: z.array().optional().describe("Exposed ports and their URLs"), ssh: z.object({ host: z.string().optional().describe("SSH host"), port: z.number().optional().describe("SSH port"), username: z.string().optional().describe("SSH username") }).optional().describe("SSH connection details"), has_internet_access: z.boolean().optional().describe("Whether outbound network access is allowed"), timeout_seconds: z.number().optional().describe("Seconds until the instance expires; set on update to extend it"), expires_at: z.string-time().optional().describe("When the instance will expire (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), on_expire: z.enum("TERMINATE", "PAUSE", "STOP", "OTHER").optional().describe("What happens when the instance expires"), idle_timeout_seconds: z.number().optional().describe("Seconds of inactivity before on_idle applies"), on_idle: z.enum("TERMINATE", "PAUSE", "STOP", "OTHER").optional().describe("What happens when the instance is idle"), project_identifier: z.string().optional().describe("Vendor project, team or app that groups the instance (reference to TaskProject)"), service_id: z.string().optional().describe("The service (app) this instance runs for, on hosting platforms"), env: z.array().optional().describe("Environment variables (write-only values)"), started_at: z.string-time().optional().describe("When the instance last started (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), terminated_at: z.string-time().optional().describe("When the instance was terminated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), metadata: z.array().optional().describe("Vendor labels, tags and metadata"), }); ``` ## Python ```python import dataclasses @dataclasses.dataclass class ComputeInstanceType(str, Enum): CONTAINER = 'CONTAINER' VM = 'VM' BAREMETAL = 'BAREMETAL' SANDBOX = 'SANDBOX' OTHER = 'OTHER' @dataclasses.dataclass class ComputeInstanceStatus(str, Enum): PROVISIONING = 'PROVISIONING' STARTING = 'STARTING' RUNNING = 'RUNNING' STOPPING = 'STOPPING' STOPPED = 'STOPPED' PAUSING = 'PAUSING' PAUSED = 'PAUSED' RESUMING = 'RESUMING' RESTARTING = 'RESTARTING' TERMINATING = 'TERMINATING' TERMINATED = 'TERMINATED' PREEMPTED = 'PREEMPTED' ERROR = 'ERROR' OTHER = 'OTHER' @dataclasses.dataclass class ComputeInstanceAllowed_actions(str, Enum): START = 'START' STOP = 'STOP' RESTART = 'RESTART' PAUSE = 'PAUSE' RESUME = 'RESUME' TERMINATE = 'TERMINATE' @dataclasses.dataclass class ComputeInstanceMarket(str, Enum): ON_DEMAND = 'ON_DEMAND' SPOT = 'SPOT' RESERVED = 'RESERVED' COMMUNITY = 'COMMUNITY' OTHER = 'OTHER' @dataclasses.dataclass class ComputeInstanceGpu_model(str, Enum): NVIDIA_GB300 = 'NVIDIA_GB300' NVIDIA_B300 = 'NVIDIA_B300' NVIDIA_GB200 = 'NVIDIA_GB200' NVIDIA_B200 = 'NVIDIA_B200' NVIDIA_GH200 = 'NVIDIA_GH200' NVIDIA_H200 = 'NVIDIA_H200' NVIDIA_H100_SXM = 'NVIDIA_H100_SXM' NVIDIA_H100_PCIE = 'NVIDIA_H100_PCIE' NVIDIA_H100_NVL = 'NVIDIA_H100_NVL' NVIDIA_A100_SXM_80GB = 'NVIDIA_A100_SXM_80GB' NVIDIA_A100_PCIE_80GB = 'NVIDIA_A100_PCIE_80GB' NVIDIA_A100_40GB = 'NVIDIA_A100_40GB' NVIDIA_L40S = 'NVIDIA_L40S' NVIDIA_L40 = 'NVIDIA_L40' NVIDIA_L4 = 'NVIDIA_L4' NVIDIA_A40 = 'NVIDIA_A40' NVIDIA_A10 = 'NVIDIA_A10' NVIDIA_RTX_PRO_6000 = 'NVIDIA_RTX_PRO_6000' NVIDIA_RTX_6000_ADA = 'NVIDIA_RTX_6000_ADA' NVIDIA_RTX_A6000 = 'NVIDIA_RTX_A6000' NVIDIA_RTX_A5000 = 'NVIDIA_RTX_A5000' NVIDIA_RTX_A4000 = 'NVIDIA_RTX_A4000' NVIDIA_RTX_5090 = 'NVIDIA_RTX_5090' NVIDIA_RTX_4090 = 'NVIDIA_RTX_4090' NVIDIA_RTX_3090 = 'NVIDIA_RTX_3090' NVIDIA_V100 = 'NVIDIA_V100' NVIDIA_T4 = 'NVIDIA_T4' AMD_MI355X = 'AMD_MI355X' AMD_MI325X = 'AMD_MI325X' AMD_MI300X = 'AMD_MI300X' AMD_MI250 = 'AMD_MI250' OTHER = 'OTHER' @dataclasses.dataclass class ComputeInstanceArchitecture(str, Enum): X86_64 = 'X86_64' ARM64 = 'ARM64' OTHER = 'OTHER' @dataclasses.dataclass class ComputeInstancePrice_unit(str, Enum): PER_GPU_HOUR = 'PER_GPU_HOUR' PER_INSTANCE_HOUR = 'PER_INSTANCE_HOUR' OTHER = 'OTHER' @dataclasses.dataclass class ComputeInstanceOn_expire(str, Enum): TERMINATE = 'TERMINATE' PAUSE = 'PAUSE' STOP = 'STOP' OTHER = 'OTHER' @dataclasses.dataclass class ComputeInstanceOn_idle(str, Enum): TERMINATE = 'TERMINATE' PAUSE = 'PAUSE' STOP = 'STOP' OTHER = 'OTHER' @dataclasses.dataclass class PropertyComputeInstanceSsh: """SSH host""" host: Optional[str] """SSH port""" port: Optional[int] """SSH username""" username: Optional[str] @dataclasses.dataclass class ComputeInstance: """Unique identifier for the instance""" id: Optional[str] """When the instance was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" created_at: Optional[str] """When the instance was last updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" updated_at: Optional[str] """Display name of the instance""" name: Optional[str] """The kind of compute unit""" type: Optional[ComputeInstanceType] """Normalized lifecycle status; set on update to start, stop, pause, resume, restart or terminate""" status: Optional[ComputeInstanceStatus] """Vendor explanation of the current status (eg. shutdown or failure reason)""" status_reason: Optional[str] """Lifecycle actions the vendor currently allows""" allowed_actions: Optional[List[ComputeInstanceAllowed_actions]] """Pricing market the instance runs in""" market: Optional[ComputeInstanceMarket] """The region the instance runs in""" region_id: Optional[str] """The template the instance was created from""" template_id: Optional[str] """Container or OS image, when not created from a template""" image: Optional[str] """The snapshot the instance was restored or forked from""" source_snapshot_id: Optional[str] """The instance this one was forked from""" parent_instance_id: Optional[str] """The GPU or instance type of this instance""" gputype_id: Optional[str] """Normalized GPU model""" gpu_model: Optional[ComputeInstanceGpu_model] """Number of GPUs attached (0 for CPU-only)""" gpu_count: Optional[int] """The vendor's own SKU or size name""" sku: Optional[str] """Number of vCPUs; may be fractional""" cpu_count: Optional[int] """System memory in MiB""" memory_mb: Optional[int] """Disk size in MiB""" disk_mb: Optional[int] """CPU architecture""" architecture: Optional[ComputeInstanceArchitecture] """List price for the instance""" price_amount: Optional[int] """Unit that price_amount is quoted in""" price_unit: Optional[ComputeInstancePrice_unit] """Currency of price_amount (ISO 4217)""" currency: Optional[str] """Volumes mounted on the instance""" volume_ids: Optional[List[List[str]]] """Exposed ports and their URLs""" endpoints: Optional[PropertyComputeInstanceEndpoints] """SSH connection details""" ssh: Optional[PropertyComputeInstanceSsh] """Whether outbound network access is allowed""" has_internet_access: Optional[bool] """Seconds until the instance expires; set on update to extend it""" timeout_seconds: Optional[int] """When the instance will expire (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" expires_at: Optional[str] """What happens when the instance expires""" on_expire: Optional[ComputeInstanceOn_expire] """Seconds of inactivity before on_idle applies""" idle_timeout_seconds: Optional[int] """What happens when the instance is idle""" on_idle: Optional[ComputeInstanceOn_idle] """Vendor project, team or app that groups the instance (reference to TaskProject)""" project_identifier: Optional[str] """The service (app) this instance runs for, on hosting platforms""" service_id: Optional[str] """Environment variables (write-only values)""" env: Optional[PropertyComputeInstanceEnv] """When the instance last started (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" started_at: Optional[str] """When the instance was terminated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" terminated_at: Optional[str] """Vendor labels, tags and metadata""" metadata: Optional[PropertyComputeInstanceMetadata] ```