Python SDK

​

Client

​

Client

@define
class Client()

• raise_on_unexpected_status - Whether or not to raise an errors.UnexpectedStatus if the API returns a status code that was not documented in the source OpenAPI document. Can also be provided as a keyword argument to the constructor.

with_headers

def with_headers(headers: dict[str, str]) -> "Client"

with_cookies

def with_cookies(cookies: dict[str, str]) -> "Client"

with_timeout

def with_timeout(timeout: httpx.Timeout) -> "Client"

set_httpx_client

def set_httpx_client(client: httpx.Client) -> "Client"

get_httpx_client

def get_httpx_client() -> httpx.Client

__enter__

def __enter__() -> "Client"

__exit__

def __exit__(*args: Any, **kwargs: Any) -> None

set_async_httpx_client

def set_async_httpx_client(async_client: httpx.AsyncClient) -> "Client"

get_async_httpx_client

def get_async_httpx_client() -> httpx.AsyncClient

__aenter__

async def __aenter__() -> "Client"

__aexit__

async def __aexit__(*args: Any, **kwargs: Any) -> None

​

AuthenticatedClient

@define
class AuthenticatedClient()

• raise_on_unexpected_status - Whether or not to raise an errors.UnexpectedStatus if the API returns a status code that was not documented in the source OpenAPI document. Can also be provided as a keyword argument to the constructor.
• token - The token to use for authentication
• prefix - The prefix to use for the Authorization header
• auth_header_name - The name of the Authorization header

with_headers

def with_headers(headers: dict[str, str]) -> "AuthenticatedClient"

with_cookies

def with_cookies(cookies: dict[str, str]) -> "AuthenticatedClient"

with_timeout

def with_timeout(timeout: httpx.Timeout) -> "AuthenticatedClient"

set_httpx_client

def set_httpx_client(client: httpx.Client) -> "AuthenticatedClient"

get_httpx_client

def get_httpx_client() -> httpx.Client

__enter__

def __enter__() -> "AuthenticatedClient"

__exit__

def __exit__(*args: Any, **kwargs: Any) -> None

set_async_httpx_client

def set_async_httpx_client(
        async_client: httpx.AsyncClient) -> "AuthenticatedClient"

get_async_httpx_client

def get_async_httpx_client() -> httpx.AsyncClient

__aenter__

async def __aenter__() -> "AuthenticatedClient"

__aexit__

async def __aexit__(*args: Any, **kwargs: Any) -> None

​

UnexpectedStatus

class UnexpectedStatus(Exception)

​

SseEvent

@define(frozen=True)
class SseEvent(Generic[T])

tail_run

def tail_run(
    *,
    client: SdkClient,
    run_id: str,
    lineage_path: str | None = None,
    signal: str | None = None,
    cursor: str | None = None
) -> Iterator[SseEvent[dict[str, Any]]] | ErrorBody | None

tail_run_async

async def tail_run_async(
    *,
    client: SdkClient,
    run_id: str,
    lineage_path: str | None = None,
    signal: str | None = None,
    cursor: str | None = None
) -> AsyncIterator[SseEvent[dict[str, Any]]] | ErrorBody | None

​

File

@define
class File()

to_tuple

def to_tuple() -> FileTypes

​

Response

@define
class Response(Generic[T])

​

Operations

​

Sandboxes & runtime

• hiloop.api.sandbox_service.sandbox_service_create_sandbox
• hiloop.api.sandbox_service.sandbox_service_create_sandbox_snapshot
• hiloop.api.sandbox_service.sandbox_service_delete_sandbox
• hiloop.api.sandbox_service.sandbox_service_delete_sandbox_snapshot
• hiloop.api.sandbox_service.sandbox_service_exec_sandbox
• hiloop.api.sandbox_service.sandbox_service_get_sandbox
• hiloop.api.sandbox_service.sandbox_service_list_sandbox_snapshots
• hiloop.api.sandbox_service.sandbox_service_list_sandboxes
• hiloop.api.sandbox_service.sandbox_service_update_sandbox

​

Volumes

• hiloop.api.volume_service.volume_service_create_volume
• hiloop.api.volume_service.volume_service_delete_volume
• hiloop.api.volume_service.volume_service_get_volume
• hiloop.api.volume_service.volume_service_list_volumes
• hiloop.api.volume_service.volume_service_publish_volume_version
• hiloop.api.volume_service.volume_service_request_volume_blob_uploads
• hiloop.api.volume_service.volume_service_start_volume_push

​

Saved & data views

• hiloop.api.telemetry_view_service.telemetry_view_service_delete_data_view
• hiloop.api.telemetry_view_service.telemetry_view_service_list_data_views
• hiloop.api.telemetry_view_service.telemetry_view_service_put_data_view
• hiloop.api.telemetry_view_service.telemetry_view_service_run_data_view

​

Annotations

• hiloop.api.annotation_service.annotation_service_annotate
• hiloop.api.annotation_service.annotation_service_annotate_range
• hiloop.api.annotation_service.annotation_service_list_annotations

​

Annotation schemas

• hiloop.api.annotation_schema_service.annotation_schema_service_archive_annotation_schema
• hiloop.api.annotation_schema_service.annotation_schema_service_get_annotation_schema
• hiloop.api.annotation_schema_service.annotation_schema_service_list_annotation_schemas
• hiloop.api.annotation_schema_service.annotation_schema_service_register_annotation_schema

​

Runs

• hiloop.api.run_service.run_service_complete_run
• hiloop.api.run_service.run_service_get_run
• hiloop.api.run_service.run_service_list_runs
• hiloop.api.run_service.run_service_start_run

​

Secrets

• hiloop.api.secret_service.secret_service_create_sandbox_secret
• hiloop.api.secret_service.secret_service_grant_sandbox_secret
• hiloop.api.secret_service.secret_service_list_sandbox_secret_grants
• hiloop.api.secret_service.secret_service_list_sandbox_secrets
• hiloop.api.secret_service.secret_service_revoke_sandbox_secret
• hiloop.api.secret_service.secret_service_rotate_sandbox_secret
• hiloop.api.secret_service.secret_service_ungrant_sandbox_secret

​

Workloads

• hiloop.api.workload_service.workload_service_add_workload_federation
• hiloop.api.workload_service.workload_service_create_workload
• hiloop.api.workload_service.workload_service_delete_workload
• hiloop.api.workload_service.workload_service_get_workload
• hiloop.api.workload_service.workload_service_list_workload_federation
• hiloop.api.workload_service.workload_service_list_workloads
• hiloop.api.workload_service.workload_service_remove_workload_federation
• hiloop.api.workload_service.workload_service_set_workload_launch_acl

​

Usage

• hiloop.api.usage_service.usage_service_get_usage_snapshot

​

Projects

• hiloop.api.project_service.project_service_create_project
• hiloop.api.project_service.project_service_delete_project
• hiloop.api.project_service.project_service_get_project
• hiloop.api.project_service.project_service_list_projects
• hiloop.api.project_service.project_service_update_project

​

Discovery

• hiloop.api.meta_service.meta_service_get_service_config

​

Identity

• hiloop.api.identity_service.identity_service_who_am_i

​

Feedback

• hiloop.api.feedback_service.feedback_service_create_feedback

​

Models

​

AddWorkloadFederationRequest

@_attrs_define
class AddWorkloadFederationRequest()

• name str | Unset - The registered workload name.
• cloud str | Unset - Cloud provider: aws, gcp, or azure.
• descriptor WorkloadFederationDescriptor | Unset - Cloud-specific parameters for one workload federation registration. Only the fields belonging to the selected cloud may be set. AWS requires role_arn and defaults an empty region to us-east-1. Google Cloud requires project_id, project_number, pool_id, and provider_id; service_account_email is optional. Microsoft Entra requires application_id and entra_tenant_id.

​

AddWorkloadFederationResponse

@_attrs_define
class AddWorkloadFederationResponse()

• federation_config WorkloadFederationConfig | Unset - One live cloud-federation registration owned by a workload. The audience is provider-canonical and server-derived from cloud and descriptor; it is the exact value the workload may request from the workload-identity issuer.

​

AnnotateRangeRequest

@_attrs_define
class AnnotateRangeRequest()

• run_id str | Unset - The run (session) the annotation belongs to.
• schema_name str | Unset - The registered annotation-schema name the payload validates against (the event name).
• range_start_ns str | Unset - Inclusive start of the annotated window, in wall-clock nanoseconds. Mutually exclusive with the event-pair form.
• range_end_ns str | Unset - Inclusive end of the annotated window, in wall-clock nanoseconds. Mutually exclusive with the event-pair form.
• payload_json str | Unset - The annotation payload as a JSON object string; validated against schema_name’s registered JSON Schema at ingest. Reserved hiloop.annotation.* keys are platform-owned and excluded.
• range_start_event_id str | Unset - The event_id whose recorded timestamp starts the annotated window. Both event endpoints must exist in run_id; the window bounds are materialized from their timestamps. Set together with range_end_event_id, and not alongside the nanosecond bounds.
• range_end_event_id str | Unset - The event_id whose recorded timestamp ends the annotated window. Set together with range_start_event_id, and not alongside the nanosecond bounds.
• event_id str | Unset - Optional caller-minted event_id for the annotation event (a 26-character ULID). Supplying one makes retries safe: re-sending the request with the same event_id returns the existing annotation instead of writing a duplicate, so an ambiguous failure (a 5xx or a lost response) can be retried blindly. The id names this logical annotation — never reuse it for different content. Omitted, the server mints a fresh id per call and a retry writes a new annotation.

​

AnnotateRequest

@_attrs_define
class AnnotateRequest()

• run_id str | Unset - The run (session) the annotation belongs to. Exactly one of run_id or project_id is set.
• schema_name str | Unset - The registered annotation-schema name the payload validates against (the event name).
• target_event_id str | Unset - The event_id of the single event this annotation is about. Only valid with run_id; empty annotates the run (or project) itself.
• payload_json str | Unset - The annotation payload as a JSON object string; validated against schema_name’s registered JSON Schema at ingest. Reserved hiloop.annotation.* keys are platform-owned and excluded.
• project_id str | Unset - The project a run-less annotation belongs to. Exactly one of run_id or project_id is set; a project-scoped annotation carries no run lineage and no target event.
• event_id str | Unset - Optional caller-minted event_id for the annotation event (a 26-character ULID). Supplying one makes retries safe: re-sending the request with the same event_id returns the existing annotation instead of writing a duplicate, so an ambiguous failure (a 5xx or a lost response) can be retried blindly. The id names this logical annotation — never reuse it for different content. Omitted, the server mints a fresh id per call and a retry writes a new annotation.

​

AnnotateResponse

@_attrs_define
class AnnotateResponse()

• event_id str | Unset - The stable event_id of the annotation event (the dedup/lookup key): the caller-minted id when the request carried one, otherwise the freshly server-minted one.

​

AnnotationSchema

@_attrs_define
class AnnotationSchema()

• id str | Unset - The config id.
• name str | Unset - The schema name — unique per org across versions (the registered name an annotation names).
• version str | Unset - The monotonic version within (org, name). The first registration is 1.
• description str | Unset - An optional human-readable description.
• json_schema str | Unset - The JSON Schema document (draft 2020-12) as a JSON string.
• archived_at str | Unset - When the config was archived (RFC 3339), or empty if it is still live.
• created_at str | Unset - When the config version was created (RFC 3339).
• promoted_fields list[PromotedField] | Unset - The fields this schema promotes from the payload into typed columns, each with its server-assigned slot. Empty when the schema promotes nothing.

​

ArchiveAnnotationSchemaRequest

@_attrs_define
class ArchiveAnnotationSchemaRequest()

• name str | Unset - The schema name to archive.
• version str | Unset - The specific version to archive. 0 (or omitted) means the latest live version.

​

ArchiveAnnotationSchemaResponse

@_attrs_define
class ArchiveAnnotationSchemaResponse()

• schema AnnotationSchema | Unset - One registered annotation-schema config: a single immutable, versioned row of the registry.

​

CompleteRunRequest

@_attrs_define
class CompleteRunRequest()

• id str | Unset - The run to complete.
• status str | Unset - The terminal status to record: succeeded, failed, or canceled.

​

CompleteRunResponse

@_attrs_define
class CompleteRunResponse()

• run Run | Unset - A run record (the subset the API returns). Intentionally carries no cost or spend roll-up: the product is generic and does not surface cost by default.

​

CreateFeedbackRequest

@_attrs_define
class CreateFeedbackRequest()

• title str | Unset - A short summary of the report. Required; at most 300 characters.
• surface str | Unset - The product surface the report is about. Required; one of cli, api, web, sandbox, telemetry, annotations, docs, or other.
• severity str | Unset - How severe the problem is. Optional; one of critical, high, medium, or low. Leave it empty for general feedback that is not a bug.
• body str | Unset - Free-form feedback text. Optional; at most 10,000 characters.
• expected str | Unset - What was expected to happen. Optional; at most 10,000 characters.
• actual str | Unset - What actually happened. Optional; at most 10,000 characters.
• repro str | Unset - Steps to reproduce the problem. Optional; at most 10,000 characters.
• evidence list[str] | Unset - Correlation keys — run, event, or artifact ids — linking the report to recorded telemetry. Optional; at most 50 entries, each at most 256 characters.
• fingerprint str | Unset - A stable, content-derived deduplication key (for example &lt;surface&gt;/<short-slug>). Enforced: a submission whose fingerprint already exists returns the original report’s id instead of storing (and surfacing) a duplicate, which makes retrying a lost response safe. When omitted, the server derives one from the report’s content, so re-sending an identical report also converges. Optional; at most 300 characters.
• hiloop_version str | Unset - The hiloop client version that produced the report. Optional; at most 100 characters.

​

CreateFeedbackResponse

@_attrs_define
class CreateFeedbackResponse()

• id str | Unset - The stored report’s id.
• relayed bool | Unset - Whether the report was surfaced to the team’s review channel. The report is stored either way, so a false here never means the feedback was lost.

​

CreateProjectRequest

@_attrs_define
class CreateProjectRequest()

• slug str | Unset - The project slug — unique within the caller’s organization.
• name str | Unset - The human-readable project name.
• description str | Unset - An optional user-assigned free-text description (at most 4 KiB). Empty leaves the project undescribed.

​

CreateProjectResponse

@_attrs_define
class CreateProjectResponse()

• project Project | Unset - A project record (the subset the API returns).

​

CreateSandboxFromImageRequest

@_attrs_define
class CreateSandboxFromImageRequest()

• image str | Unset - The unmodified OCI image reference to start from.
• ttl_seconds int | Unset - Sandbox lifetime in seconds. Omit it to use the deployment default.
• storage_class CreateSandboxFromImageRequestStorageClass | Unset - Storage behavior for the sandbox. Omit it to use durable storage when restoring a snapshot, or standard storage for an image/platform-default create. Default: CreateSandboxFromImageRequestStorageClass.STANDARD.
• ports list[int] | Unset - Unique guest TCP ports in the range 1-65535. Returned endpoints are authenticated private session-plane connections, not public preview URLs.
• volumes list[SandboxVolumeMount] | Unset - Pre-registered volumes to mount, each pinned to its current version at admission.
• secrets list[SandboxSecretBinding] | Unset - Pre-registered secrets to bind for proof-bound request-time delivery.
• metadata CreateSandboxFromImageRequestMetadata | Unset - Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.
• name str | Unset - Optional customer-supplied name, unique among the project’s sandboxes that have not finished deleting. It must be 1-63 characters: lowercase letters or digits, with interior hyphens allowed. Omit it to leave the sandbox unnamed; the server never generates a name. A duplicate returns 409 name_conflict; a terminated sandbox’s name is free to reuse, and its record keeps the name for history.
• resources ResourceSpec | Unset - Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it.
• command list[str] | Unset - Argv that replaces the image’s own entrypoint as the sandbox’s first process. Omit it to run the image’s ENTRYPOINT/CMD unchanged, which is what an image built to hold itself open wants. Supply it for an image whose entrypoint runs a task and exits, such as a base OS image or a build tool: a sandbox is something you attach to, and it lives only as long as its first process. The argv is executed directly rather than through a shell, so pipes and redirection belong inside a command you name explicitly. The executable must not be empty; at most 256 entries, each at most 4096 characters.
• workspace_capacity_gib int | Unset - Durable workspace capacity in whole GiB. A root create may omit it to use the deployment default; a snapshot create inherits the snapshot-time value. A legacy snapshot whose capacity predates stamping requires an explicit value. This field is valid only with durable storage; standard storage has no persistent workspace claim.
• placement_class CreateSandboxFromImageRequestPlacementClass | Unset - Capacity posture for this sandbox. Omit it to use standard placement.
• idle_timeout_seconds int | Unset - Idle duration in seconds after which a running sandbox is stopped. Omit it to use the deployment default; when the deployment has no default, idle stopping is disabled. Values are from 60 through 86400.
• shared_filesystems list[SandboxSharedFilesystemMount] | Unset - Deployment-registered shared filesystems to mount. Shared filesystems are external to this sandbox’s snapshots; durable storage is required for the sandbox’s private runtime state.
• network_access CreateSandboxFromImageRequestNetworkAccess | Unset - Outbound-network posture. Omit it to use public access.

​

CreateSandboxFromImageRequestMetadata

@_attrs_define
class CreateSandboxFromImageRequestMetadata()

​

CreateSandboxFromSnapshotRequest

@_attrs_define
class CreateSandboxFromSnapshotRequest()

• snapshot_id str - The snapshot to restore as a new child sandbox.
• ttl_seconds int | Unset - Sandbox lifetime in seconds. Omit it to use the deployment default.
• storage_class CreateSandboxFromSnapshotRequestStorageClass | Unset - Storage behavior for the sandbox. Omit it to use durable storage when restoring a snapshot, or standard storage for an image/platform-default create. Default: CreateSandboxFromSnapshotRequestStorageClass.DURABLE.
• ports list[int] | Unset - Unique guest TCP ports in the range 1-65535. Returned endpoints are authenticated private session-plane connections, not public preview URLs.
• volumes list[SandboxVolumeMount] | Unset - Pre-registered volumes to mount, each pinned to its current version at admission.
• secrets list[SandboxSecretBinding] | Unset - Pre-registered secrets to bind for proof-bound request-time delivery.
• image_override str | Unset - The image to run the restored workspace on, when it should not be the one the snapshot recorded. Only meaningful with snapshot_id: a snapshot carries workspace bytes, and this names the runtime they are materialized onto, which is how a sandbox takes a newer base image without losing what is in its workspace. Omit it to run the image the snapshot recorded.
• metadata CreateSandboxFromSnapshotRequestMetadata | Unset - Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.
• name str | Unset - Optional customer-supplied name, unique among the project’s sandboxes that have not finished deleting. It must be 1-63 characters: lowercase letters or digits, with interior hyphens allowed. Omit it to leave the sandbox unnamed; the server never generates a name. A duplicate returns 409 name_conflict; a terminated sandbox’s name is free to reuse, and its record keeps the name for history.
• resources ResourceSpec | Unset - Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it.
• command list[str] | Unset - Argv that replaces the image’s own entrypoint as the sandbox’s first process. Omit it to run the image’s ENTRYPOINT/CMD unchanged, which is what an image built to hold itself open wants. Supply it for an image whose entrypoint runs a task and exits, such as a base OS image or a build tool: a sandbox is something you attach to, and it lives only as long as its first process. The argv is executed directly rather than through a shell, so pipes and redirection belong inside a command you name explicitly. The executable must not be empty; at most 256 entries, each at most 4096 characters.
• workspace_capacity_gib int | Unset - Durable workspace capacity in whole GiB. A root create may omit it to use the deployment default; a snapshot create inherits the snapshot-time value. A legacy snapshot whose capacity predates stamping requires an explicit value. This field is valid only with durable storage; standard storage has no persistent workspace claim.
• placement_class CreateSandboxFromSnapshotRequestPlacementClass | Unset - Capacity posture for this sandbox. Omit it to use standard placement.
• idle_timeout_seconds int | Unset - Idle duration in seconds after which a running sandbox is stopped. Omit it to use the deployment default; when the deployment has no default, idle stopping is disabled. Values are from 60 through 86400.
• shared_filesystems list[SandboxSharedFilesystemMount] | Unset - Deployment-registered shared filesystems to mount. Shared filesystems are external to this sandbox’s snapshots; durable storage is required for the sandbox’s private runtime state.
• network_access CreateSandboxFromSnapshotRequestNetworkAccess | Unset - Outbound-network posture. Omit it to use public access.

​

CreateSandboxFromSnapshotRequestMetadata

@_attrs_define
class CreateSandboxFromSnapshotRequestMetadata()

​

CreateSandboxResponse

@_attrs_define
class CreateSandboxResponse()

• id str - The new sandbox id. Poll GetSandbox with this id for observed lifecycle state.
• request_state CreateSandboxResponseRequestState - The accepted mutation-request state, distinct from observed sandbox lifecycle state.
• run_id str - The ambient run that receives telemetry captured for this sandbox. An idempotent create retry returns the same run id.

​

CreateSandboxSecretRequest

@_attrs_define
class CreateSandboxSecretRequest()

• name str | Unset - The secret name — unique within the caller’s organization.
• value str | Unset - The secret value. WRITE-ONLY: stored encrypted for proof-bound delivery and never returned by these management APIs.
• dest_host str | Unset - The exact public HTTPS destination. Must be a bare DNS hostname such as api.openai.com, not a URL or IP address; stored in canonical lowercase form. Must be empty for sandbox-environment delivery.
• delivery CreateSandboxSecretRequestDelivery | Unset - The only trusted data plane allowed to release this secret. Defaults to generic secret egress.

​

CreateSandboxSecretResponse

@_attrs_define
class CreateSandboxSecretResponse()

• secret SandboxSecret | Unset - A sandbox-secret record — metadata only, never the value.

​

CreateSandboxSnapshotBody

@_attrs_define
class CreateSandboxSnapshotBody()

• name str | Unset - Optional human-readable snapshot name used by list filtering, from 1 through 128 characters.
• wait_remote bool | Unset - When true, wait for confirmed remote replication before returning the receipt. When false, return after the local storage snapshot exists. The wait is bounded by wait_timeout_seconds. Default: False.
• wait_timeout_seconds int | Unset - Remote-replication wait bound in seconds, from 1 through 25. At the deadline, return the same snapshot id with truthful local durability rather than holding the request longer.

​

CreateSandboxSnapshotResponse

@_attrs_define
class CreateSandboxSnapshotResponse()

• snapshot_id str - The new immutable snapshot id.
• durability CreateSandboxSnapshotResponseDurability - Durability proven before this receipt was returned.

​

CreateVolumeRequest

@_attrs_define
class CreateVolumeRequest()

• project_id str | Unset - The project the volume belongs to.
• name str | Unset - The volume name — unique within the project (letters, digits, dots, dashes, underscores; at most 100 characters).
• description str | Unset - An optional user-assigned free-text description (at most 4 KiB). Empty leaves the volume undescribed.
• quota_bytes str | Unset - Storage quota in bytes (required). A quota, not an allocation; at most 2 TiB per volume.

​

CreateVolumeResponse

@_attrs_define
class CreateVolumeResponse()

• volume Volume | Unset - A volume record (the subset the API returns).

​

CreateWorkloadRequest

@_attrs_define
class CreateWorkloadRequest()

• name str | Unset - The workload name to register — unique within the organization. Lowercase letters, digits, ., _, and -; must start and end with a letter or digit; at most 100 characters.
• description str | Unset - A free-text description of what the workload is for. Optional.

​

CreateWorkloadResponse

@_attrs_define
class CreateWorkloadResponse()

• workload Workload | Unset - A registered workload identity, scoped to the caller’s organization.

​

DataView

@_attrs_define
class DataView()

• name str | Unset - The view name, unique within an organization among non-deleted views.
• description str | Unset - A human description, surfaced in the console switcher.
• spec DataViewSpec | Unset - The data-view spec as opaque JSON — the engine’s tagged DataViewSpec: a raw Sql SELECT, plus opaque render config. Carried as a Struct so the spec schema lives in ONE place (the engine’s serde types); the service never re-models it. Re-validated against the current column allowlist on store and on every run, so a view referencing a dropped column fails closed with INVALID_ARGUMENT rather than serving a stale result.
• spec_version str | Unset - Monotonic per-edit version; the store bumps it on each upsert.

​

DataViewSpec

@_attrs_define
class DataViewSpec()

​

DeleteDataViewResponse

@_attrs_define
class DeleteDataViewResponse()

​

DeleteProjectResponse

@_attrs_define
class DeleteProjectResponse()

• runs_deleted str | Unset - The number of runs deleted.
• volumes_deleted str | Unset - The number of volumes deleted.
• secrets_deleted str | Unset - The number of project-scoped secrets deleted.
• api_keys_deleted str | Unset - The number of project-scoped API keys deleted (keys scoped to the whole organization are untouched).

​

DeleteSandboxResponse

@_attrs_define
class DeleteSandboxResponse()

• id str - The sandbox id whose deletion was accepted.
• request_state DeleteSandboxResponseRequestState - The accepted mutation-request state, distinct from observed sandbox lifecycle state.

​

DeleteSandboxSnapshotResponse

@_attrs_define
class DeleteSandboxSnapshotResponse()

​

DeleteVolumeResponse

@_attrs_define
class DeleteVolumeResponse()

​

DeleteWorkloadResponse

@_attrs_define
class DeleteWorkloadResponse()

​

ErrorBody

@_attrs_define
class ErrorBody()

• code str - Stable machine-readable error code in snake_case.
• message str - Human-readable description; clients must not parse it. details (ErrorDetails | Unset):
• request_id str | Unset - Correlation id present on server faults.

​

ErrorDetails

@_attrs_define
class ErrorDetails()

​

ExecSandboxBody

@_attrs_define
class ExecSandboxBody()

• cmd list[str] - Command and arguments. The first entry is a non-empty executable; at most 256 entries are accepted and each entry is at most 4096 characters.
• timeout_seconds int | Unset - Execution timeout in whole seconds, from 1 through 3600. Omit it to use the server default; sub-second budgets are outside this version.
• secret_environment list[SandboxExecSecretEnvironment] | Unset - Secret references released atomically into the child environment. No value crosses this public API. Omit for ordinary execution.

​

ExecSandboxCompletedResponse

@_attrs_define
class ExecSandboxCompletedResponse()

• stdout str - Buffered standard output. It may contain partial output on a timeout or an indeterminate outcome.
• stderr str - Buffered standard error. It may contain partial output on a timeout or an indeterminate outcome.
• exit_ int - The process exit code for a completed command, including zero.
• truncated bool - Whether stdout or stderr was truncated at the server-configured combined output cap. The default cap is no more than 1 MiB. Truncation does not replace the real process outcome.

​

ExecSandboxIndeterminateResponse

@_attrs_define
class ExecSandboxIndeterminateResponse()

• stdout str - Buffered standard output. It may contain partial output on a timeout or an indeterminate outcome.
• stderr str - Buffered standard error. It may contain partial output on a timeout or an indeterminate outcome.
• indeterminate SandboxExecIndeterminate - Presence marker returned when the command was dispatched but its execution channel was lost before an outcome could be read, so the service cannot say what the command did. This is not a failure to run. The command may have run to completion, and any output collected before the channel was lost is still returned. Treat it as “unknown”, never as “did not run”: re-issuing a command that is not safe to run twice requires an Idempotency-Key, which replays the recorded outcome instead of executing again.
• truncated bool - Whether stdout or stderr was truncated at the server-configured combined output cap. The default cap is no more than 1 MiB. Truncation does not replace the real process outcome.

​

ExecSandboxTimedOutResponse

@_attrs_define
class ExecSandboxTimedOutResponse()

• stdout str - Buffered standard output. It may contain partial output on a timeout or an indeterminate outcome.
• stderr str - Buffered standard error. It may contain partial output on a timeout or an indeterminate outcome.
• timeout SandboxExecTimeout - Presence marker returned when an execution exceeded its requested timeout.
• truncated bool - Whether stdout or stderr was truncated at the server-configured combined output cap. The default cap is no more than 1 MiB. Truncation does not replace the real process outcome.

​

GetAnnotationSchemaResponse

@_attrs_define
class GetAnnotationSchemaResponse()

• schema AnnotationSchema | Unset - One registered annotation-schema config: a single immutable, versioned row of the registry.

​

GetProjectResponse

@_attrs_define
class GetProjectResponse()

• project Project | Unset - A project record (the subset the API returns).

​

GetRunResponse

@_attrs_define
class GetRunResponse()

• run Run | Unset - A run record (the subset the API returns). Intentionally carries no cost or spend roll-up: the product is generic and does not surface cost by default.

​

GetSandboxResponse

@_attrs_define
class GetSandboxResponse()

• sandbox SandboxFromImage | SandboxFromSnapshot - One organization-scoped sandbox and its observed state.

​

GetServiceConfigResponse

@_attrs_define
class GetServiceConfigResponse()

• telemetry_endpoint str | Unset - Client-visible telemetry gRPC endpoint.
• login_url str | Unset - API URL used to start the browser login flow.

​

GetUsageSnapshotResponse

@_attrs_define
class GetUsageSnapshotResponse()

• snapshot UsageSnapshot | Unset - Point-in-time quota usage for the caller’s org.

​

GetVolumeResponse

@_attrs_define
class GetVolumeResponse()

• volume Volume | Unset - A volume record (the subset the API returns).

​

GetWorkloadResponse

@_attrs_define
class GetWorkloadResponse()

• workload Workload | Unset - A registered workload identity, scoped to the caller’s organization.

​

GrantSandboxSecretRequest

@_attrs_define
class GrantSandboxSecretRequest()

• id str | Unset - The secret id to grant.
• subject_kind GrantSandboxSecretRequestSubjectKind | Unset - The principal kind.
• subject_id str | Unset - The principal’s immutable id within subject_kind.

​

GrantSandboxSecretResponse

@_attrs_define
class GrantSandboxSecretResponse()

• grant SandboxSecretGrant | Unset - One exact principal allowed to use one secret. Secret metadata visibility does not imply this authority.

​

ListAnnotationSchemasResponse

@_attrs_define
class ListAnnotationSchemasResponse()

• schemas list[AnnotationSchema] | Unset - The configs in the caller’s organization. By default the latest live version per name; with include_archived, every version, newest first.

​

ListAnnotationsResponse

@_attrs_define
class ListAnnotationsResponse()

• annotations list[ListAnnotationsResponseAnnotationsItem] | Unset - One annotation per row, newest first. Each row carries the annotation’s identity and anchor (event_id, run_id — absent on project-scoped rows — project_id, lineage_path, the schema name, ts_wall_ns, principal), its target (target_event_id, or the range bounds range_start_ns/range_end_ns plus range_start_event_id/range_end_event_id when the range was event-bounded), and the schema-validated payload as a raw JSON object string under payload_json — the exact bytes that were annotated (the write-side payload_json), so payload values of every JSON type, including 64-bit integers, read back unchanged. Row fields are encoded canonically: snake_case keys, 64-bit integers as decimal strings, absent fields omitted.
• skipped list[SkippedAnnotation] | Unset - Stored rows this listing could not decode (a legacy or corrupt storage shape), one entry per skipped row. The readable annotations above still serve in full; a listing that omits rows says so here rather than failing outright or dropping them silently. Empty on a healthy store.
• superseded_count str | Unset - How many stored versions the default latest-wins view hid because a newer write shares their supersession key. Zero when nothing was superseded, and always zero with history (which returns every version). A non-zero count means acked writes are stored but not shown here — list with history to read them all.

​

ListAnnotationsResponseAnnotationsItem

@_attrs_define
class ListAnnotationsResponseAnnotationsItem()

​

ListDataViewsResponse

@_attrs_define
class ListDataViewsResponse()

• views list[DataView] | Unset - The organization’s structured data views.

​

ListProjectsResponse

@_attrs_define
class ListProjectsResponse()

• projects list[Project] | Unset - The projects on this page, newest first.
• next_page_token str | Unset - The token to pass as page_token to fetch the next page. Empty when there are no more results.

​

ListRunsResponse

@_attrs_define
class ListRunsResponse()

• runs list[Run] | Unset - The runs on this page, newest first.
• next_page_token str | Unset - The token to pass as page_token to fetch the next page. Empty when there are no more results.

​

ListSandboxSecretGrantsResponse

@_attrs_define
class ListSandboxSecretGrantsResponse()

• grants list[SandboxSecretGrant] | Unset - At most 200 exact grants, sorted by kind and immutable id.

​

ListSandboxSecretsResponse

@_attrs_define
class ListSandboxSecretsResponse()

• secrets list[SandboxSecret] | Unset - The secrets on this page, newest first — metadata only, never the value.
• next_page_token str | Unset - The token to pass as page_token to fetch the next page. Empty when there are no more results.

​

ListSandboxSnapshotsResponse

@_attrs_define
class ListSandboxSnapshotsResponse()

• snapshots list[SandboxSnapshot] - The snapshots on this page, ordered by created_at descending then id descending, including their parent lineage edges.
• next_page_token str - Token for the next page. Empty means this is the final page.

​

ListSandboxesResponse

@_attrs_define
class ListSandboxesResponse()

• sandboxes list[SandboxFromImage | SandboxFromSnapshot] - The sandboxes on this page, ordered by created_at descending then id descending.
• next_page_token str - Token for the next page. Empty means this is the final page.

​

ListVolumesResponse

@_attrs_define
class ListVolumesResponse()

• volumes list[Volume] | Unset - The volumes on this page, newest first.
• next_page_token str | Unset - The token to pass as page_token to fetch the next page. Empty when there are no more results.

​

ListWorkloadFederationResponse

@_attrs_define
class ListWorkloadFederationResponse()

• federation_configs list[WorkloadFederationConfig] | Unset - The workload’s live registrations, in creation order.

​

ListWorkloadsResponse

@_attrs_define
class ListWorkloadsResponse()

• workloads list[Workload] | Unset - The organization’s registered workloads, by name.

​

MetadataReplacement

@_attrs_define
class MetadataReplacement()

• entries MetadataReplacementEntries | Unset - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.

​

MetadataReplacementEntries

@_attrs_define
class MetadataReplacementEntries()

​

OrgRef

@_attrs_define
class OrgRef()

• id str | Unset - The organization id.
• slug str | Unset - The organization slug.

​

Principal

@_attrs_define
class Principal()

• kind str | Unset - The kind of principal: “user” (a human identity), “service_account” (a machine credential not bound to a user), or “workload” (a credential bound to a registered workload identity).
• id str | Unset - The principal’s stable id: the user’s id for a user, the API key’s id for a service account or a workload.
• email str | Unset - The user’s primary email. Empty for a service-account or workload principal.
• key_id str | Unset - The presented API key’s id. Empty for a browser-session login (no key is involved).
• key_name str | Unset - The presented API key’s name — how this principal is displayed in listings and attribution. Empty for a browser-session login.
• workload_name str | Unset - The bound workload’s registered name — how a workload principal is displayed in listings and attribution. Empty unless the presented credential is bound to a registered workload.

​

Project

@_attrs_define
class Project()

• id str | Unset - The project id.
• slug str | Unset - The project slug — unique within the org.
• name str | Unset - The human-readable project name.
• created_at str | Unset - When the project was created (RFC 3339).
• version str | Unset - Optimistic-concurrency version, bumped on every update. Echo it back as the If-Match request header to make a later update conditional — if the project changed meanwhile the server rejects the update with error code precondition_failed instead of overwriting.
• run_count str | Unset - The total number of runs in the project, computed server-side across all of the project’s runs (not just one page).
• last_run_at str | Unset - When the most recent run in the project was created (RFC 3339), or empty when the project has no runs yet.
• description str | Unset - User-assigned free-text description (at most 4 KiB). Empty when unset.
• created_by str | Unset - Stable id of the principal that created the project — the API key (or user) that performed the create, recorded server-side, never client-supplied. Resolve it to a display name via the principals listing. Empty for projects created before attribution was recorded.
• updated_at str | Unset - When the project was last updated (RFC 3339). Equal to created_at until the first update.

​

PromotedField

@_attrs_define
class PromotedField()

• field str | Unset - The payload field name to promote (e.g. “score”). Must be a field the schema’s payload carries.
• type_ PromotedFieldType | Unset - The storage type to lift the field into.
• identity bool | Unset - Whether this field is part of the latest-wins supersession identity. The default supersession key is the annotated target plus the schema name; declaring identity fields refines it (e.g. mark an “annotator” field identity to keep the latest write per annotator). Identity fields must be promoted, since dedup partitions on the typed column.
• bloom bool | Unset - Request a point-lookup bloom filter for this field (str only; default false). Useful for a high-cardinality promoted id queried by exact match.
• slot str | Unset - The server-assigned physical column the field binds to (read-only; ignored on a register request, populated on the stored/returned schema).

​

PublishVolumeVersionRequest

@_attrs_define
class PublishVolumeVersionRequest()

• volume_id str | Unset - The volume to publish the version on.
• push_id str | Unset - The push handle from StartVolumePush, naming the uploaded manifest.

​

PublishVolumeVersionResponse

@_attrs_define
class PublishVolumeVersionResponse()

• version VolumeVersion | Unset - One immutable, committed volume version. The digest of the version’s manifest (the canonical file listing) is the version’s identity: identical content under the same parent always yields the same digest, and a version can never change after it is published.

​

PutDataViewRequest

@_attrs_define
class PutDataViewRequest()

• name str | Unset - The view name (unique within the organization); supplied by the path.
• description str | Unset - An optional human description.
• spec PutDataViewRequestSpec | Unset - The data-view spec (opaque JSON, the engine’s tagged DataViewSpec). Compile-validated before store.

​

PutDataViewRequestSpec

@_attrs_define
class PutDataViewRequestSpec()

​

QueryResponse

@_attrs_define
class QueryResponse()

• rows list[QueryResponseRowsItem] | Unset - One flat JSON object per result row: column name -> bare scalar value, nulls omitted, 64-bit integers as decimal strings. For aggregate surfaces the columns are the grouping columns plus one per aggregate metric (e.g. “sum_input_tokens”). Reused by the view service.
• columns list[str] | Unset - The result set’s declared column names, in projection order. Present even when a column is NULL in every row (per-row nulls are omitted), so a selected-but-empty column stays visible.

​

QueryResponseRowsItem

@_attrs_define
class QueryResponseRowsItem()

​

QuotaDetails

@_attrs_define
class QuotaDetails()

​

QuotaLimit

@_attrs_define
class QuotaLimit()

• metric str | Unset - Stable metric name used by quota errors and usage displays.
• limit str | Unset - Configured cap for the caller’s organization.
• current str | Unset - Current usage. Omitted for rate limits.

​

RegisterAnnotationSchemaRequest

@_attrs_define
class RegisterAnnotationSchemaRequest()

• name str | Unset - The schema name — unique per organization across versions. A new registration of an existing name creates the next version; an unseen name starts at version 1.
• json_schema str | Unset - The JSON Schema document (draft 2020-12) as a JSON string. Must be a JSON object.
• description str | Unset - An optional human-readable description for this version.
• promoted_fields list[PromotedField] | Unset - The payload fields to promote into typed columns for this version. The caller sets field/type/identity/bloom; the server assigns each field’s slot, keeping a previously promoted field’s slot and type. Registration is rejected if a field re-declares a different type, or if the schema has bound more fields of a type, across all its versions, than the slot pool holds.

​

RegisterAnnotationSchemaResponse

@_attrs_define
class RegisterAnnotationSchemaResponse()

• schema AnnotationSchema | Unset - One registered annotation-schema config: a single immutable, versioned row of the registry.

​

RemoveWorkloadFederationResponse

@_attrs_define
class RemoveWorkloadFederationResponse()

​

RequestVolumeBlobUploadsRequest

@_attrs_define
class RequestVolumeBlobUploadsRequest()

• volume_id str | Unset - The volume the blobs are being pushed for.
• blobs list[VolumeBlobRef] | Unset - The blobs to upload, at most 512 per request. Repeat the call in batches for larger pushes; it is read-only on the volume itself, so batches may run concurrently.

​

RequestVolumeBlobUploadsResponse

@_attrs_define
class RequestVolumeBlobUploadsResponse()

• uploads list[VolumeBlobUpload] | Unset - One entry per distinct requested digest: either already present, or an upload URL.
• expires_in_seconds int | Unset - How long the returned upload URLs stay valid, in seconds.

​

ResourceSpec

@_attrs_define
class ResourceSpec()

• memory_mb int | Unset - Requested memory in MB (mebibytes: 1024 MB = 1 GiB), from 1 through 1048576. Omit it to use the deployment default.
• gpus ResourceSpecGpus | Unset - Requested accelerators.
• cpu_millis int | Unset - Requested CPU in milliCPU, from 50 through 128000. 1000 milliCPU is one vCPU. Omit it to use the deployment default.

​

ResourceSpecGpus

@_attrs_define
class ResourceSpecGpus()

• count int | Unset - Integral accelerator count.
• models list[str] | Unset - Ordered fallback list of acceptable accelerator models. An empty list accepts any advertised model.

​

RevokeSandboxSecretResponse

@_attrs_define
class RevokeSandboxSecretResponse()

• secret SandboxSecret | Unset - A sandbox-secret record — metadata only, never the value.

​

RotateSandboxSecretRequest

@_attrs_define
class RotateSandboxSecretRequest()

• id str | Unset - The secret id to rotate.
• value str | Unset - The new secret value. WRITE-ONLY: stored encrypted as a new version and never returned.

​

RotateSandboxSecretResponse

@_attrs_define
class RotateSandboxSecretResponse()

• secret SandboxSecret | Unset - A sandbox-secret record — metadata only, never the value.

​

Run

@_attrs_define
class Run()

• id str | Unset - The run id (a client-supplied ULID, shared with telemetry).
• project_id str | Unset - The project the run belongs to.
• label str | Unset - An optional human-readable label.
• status str | Unset - The run lifecycle status: pending, running, succeeded, failed, or canceled.
• created_by str | Unset - The stable id of the principal that created the run — the API key (or user) that performed the start, recorded server-side. Empty when unrecorded.
• started_at str | Unset - When the run started executing (RFC 3339), empty if it has not started.
• ended_at str | Unset - When the run finished (RFC 3339), empty if it is still in flight.
• created_at str | Unset - When the run record was created (RFC 3339).
• parent_run_id str | Unset - The run this run continued from. Empty for a tree root.
• root_run_id str | Unset - The root of this run’s tree (equal to id for a root). Lets the whole tree resolve in one indexed lookup.
• lineage_path str | Unset - The materialized path of run ids from the root to this run, as a dotted label (e.g. “root_ulid.child_ulid”). Sorts in creation order and addresses the subtree by prefix.
• last_activity_at str | Unset - When the run last showed a liveness signal (RFC 3339): the time of its most recent telemetry event, or started_at for a run that has emitted no events yet. Derived at read time, and only for a running run. Empty for every other run, and empty when the signal is temporarily unavailable.
• stale bool | Unset - True when last_activity_at is older than the staleness window (15 minutes): the run still reads running — no terminal state is ever recorded on the creator’s behalf — but its creator has gone quiet, so readers should render it as running (stale). Always false when last_activity_at is empty.
• executing_principal str | Unset - The stable id of the identity this run executes AS: the registered workload’s id when the launch declared one, otherwise the launcher’s own principal id (matching created_by). Empty on runs that predate executing-identity recording.
• executing_kind str | Unset - The executing identity’s kind: user, service_account, or workload. Empty on runs that predate executing-identity recording.

​

SandboxActivity

@_attrs_define
class SandboxActivity()

• at str | Unset - When the activity was last observed, in RFC 3339 form. While a command is running or a session is held open, this advances periodically rather than only at the end.
• source SandboxActivitySource | Unset - What produced it.

​

SandboxEndpoint

@_attrs_define
class SandboxEndpoint()

• port int - The guest TCP port exposed by this endpoint.
• url str - The authenticated URL clients use to reach the port.

​

SandboxErrorBody

@_attrs_define
class SandboxErrorBody()

• code str - Stable machine-readable error code in snake_case.
• message str - Human-readable description; clients must not parse it.
• request_id str - Correlation id for support and diagnostics.

​

SandboxExecIndeterminate

@_attrs_define
class SandboxExecIndeterminate()

​

SandboxExecSecretEnvironment

@_attrs_define
class SandboxExecSecretEnvironment()

• secret_name str | Unset - Name of an active sandbox-environment secret in the caller’s organization, at most 128 bytes.
• variable_name str | Unset - POSIX environment variable name populated in the child process, at most 128 bytes.

​

SandboxExecTimeout

@_attrs_define
class SandboxExecTimeout()

​

SandboxFromImage

@_attrs_define
class SandboxFromImage()

• id str - The stable sandbox id.
• state SandboxFromImageState - The current observed lifecycle state.
• image str - The OCI image reference used by a root sandbox.
• storage_class SandboxFromImageStorageClass - The backing storage behavior selected at creation.
• endpoints list[SandboxEndpoint] - Authenticated private session-plane port endpoints. Empty until an endpoint is available; these are not public preview URLs.
• lineage_path str - The immutable dotted lineage from the root sandbox to this sandbox. An image-created root uses its own id. A snapshot-created child appends its id to the parent snapshot’s lineage_path.
• metadata SandboxFromImageMetadata - Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.
• created_at datetime.datetime - When the sandbox was accepted, in RFC 3339 form.
• updated_at datetime.datetime - When the sandbox record last changed, in RFC 3339 form.
• volumes list[SandboxPinnedVolume] - Admitted volumes with the immutable version pinned for this sandbox.
• workload_image str - The OCI image the workload is actually running. For a root sandbox this repeats the source above; for one restored from a snapshot it is the resolved image, which is the snapshot’s own unless the create named a different one. Read this rather than inferring an image from lineage — a restored sandbox does not necessarily run what its parent ran.
• placement_class SandboxFromImagePlacementClass - The immutable capacity posture selected at creation.
• expires_at datetime.datetime | Unset - The expiry time in RFC 3339 form. Omitted when the sandbox has no expiry.
• ssh SandboxSshConnection | Unset - SSH connection information for a ready or running sandbox.
• state_reason SandboxStateReason | Unset - A stable reason attached to a failed or quarantined lifecycle state.
• name str | Unset - Customer-supplied name, unique among the project’s sandboxes that have not finished deleting. Omitted when no name was supplied at creation.
• resources ResourceSpec | Unset - Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it.
• created_by str | Unset - Stable id of the principal that created the sandbox: the presented API key’s id, or the session user’s id. Empty when the creator was not recorded.
• last_activity SandboxActivity | Unset - The most recent activity observed against a sandbox. Activity is what the service saw: a command submitted or still running, a session opened or still held, or a change to the sandbox itself. Work happening inside the sandbox that the service cannot see does not count.
• workspace_capacity_gib int | Unset - Durable workspace capacity in whole GiB. Omitted for standard storage and records that predate capacity stamping.
• idle_timeout_seconds int | Unset - The resolved idle-stop duration in seconds. Omitted when idle stopping is disabled.
• idle_deadline datetime.datetime | Unset - The next idle-stop deadline in RFC 3339 form. Omitted while the sandbox is not running or the controller has not reported its activity clock yet.
• shared_filesystems list[SandboxSharedFilesystemMount] | Unset - Shared filesystem selections admitted for this sandbox. These echo only the logical id, subdirectory, and guest path; deployment claim names and backend coordinates stay private.

​

SandboxFromImageMetadata

@_attrs_define
class SandboxFromImageMetadata()

​

SandboxFromSnapshot

@_attrs_define
class SandboxFromSnapshot()

• id str - The stable sandbox id.
• state SandboxFromSnapshotState - The current observed lifecycle state.
• snapshot_id str - The parent snapshot restored by a child sandbox.
• storage_class SandboxFromSnapshotStorageClass - The backing storage behavior selected at creation.
• endpoints list[SandboxEndpoint] - Authenticated private session-plane port endpoints. Empty until an endpoint is available; these are not public preview URLs.
• lineage_path str - The immutable dotted lineage from the root sandbox to this sandbox. An image-created root uses its own id. A snapshot-created child appends its id to the parent snapshot’s lineage_path.
• metadata SandboxFromSnapshotMetadata - Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.
• created_at datetime.datetime - When the sandbox was accepted, in RFC 3339 form.
• updated_at datetime.datetime - When the sandbox record last changed, in RFC 3339 form.
• volumes list[SandboxPinnedVolume] - Admitted volumes with the immutable version pinned for this sandbox.
• workload_image str - The OCI image the workload is actually running. For a root sandbox this repeats the source above; for one restored from a snapshot it is the resolved image, which is the snapshot’s own unless the create named a different one. Read this rather than inferring an image from lineage — a restored sandbox does not necessarily run what its parent ran.
• placement_class SandboxFromSnapshotPlacementClass - The immutable capacity posture selected at creation.
• expires_at datetime.datetime | Unset - The expiry time in RFC 3339 form. Omitted when the sandbox has no expiry.
• ssh SandboxSshConnection | Unset - SSH connection information for a ready or running sandbox.
• state_reason SandboxStateReason | Unset - A stable reason attached to a failed or quarantined lifecycle state.
• name str | Unset - Customer-supplied name, unique among the project’s sandboxes that have not finished deleting. Omitted when no name was supplied at creation.
• resources ResourceSpec | Unset - Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it.
• created_by str | Unset - Stable id of the principal that created the sandbox: the presented API key’s id, or the session user’s id. Empty when the creator was not recorded.
• last_activity SandboxActivity | Unset - The most recent activity observed against a sandbox. Activity is what the service saw: a command submitted or still running, a session opened or still held, or a change to the sandbox itself. Work happening inside the sandbox that the service cannot see does not count.
• workspace_capacity_gib int | Unset - Durable workspace capacity in whole GiB. Omitted for standard storage and records that predate capacity stamping.
• idle_timeout_seconds int | Unset - The resolved idle-stop duration in seconds. Omitted when idle stopping is disabled.
• idle_deadline datetime.datetime | Unset - The next idle-stop deadline in RFC 3339 form. Omitted while the sandbox is not running or the controller has not reported its activity clock yet.
• shared_filesystems list[SandboxSharedFilesystemMount] | Unset - Shared filesystem selections admitted for this sandbox. These echo only the logical id, subdirectory, and guest path; deployment claim names and backend coordinates stay private.

​

SandboxFromSnapshotMetadata

@_attrs_define
class SandboxFromSnapshotMetadata()

​

SandboxNetworkAccessReceipt

@_attrs_define
class SandboxNetworkAccessReceipt()

​

SandboxNetworkPolicyObservation

@_attrs_define
class SandboxNetworkPolicyObservation()

​

SandboxPinnedVolume

@_attrs_define
class SandboxPinnedVolume()

• volume_id str - The mounted volume id.
• version str - The immutable volume version pinned at admission.
• target_path str - The absolute mount path inside the sandbox.
• name str | Unset - The mounted volume’s name as resolved at admission. Empty when the volume had no name.

​

SandboxQuotaErrorBody

@_attrs_define
class SandboxQuotaErrorBody()

• code str - Stable machine-readable error code in snake_case.
• message str - Human-readable description; clients must not parse it.
• request_id str - Correlation id for support and diagnostics.
• metric str - Stable name of the exhausted quota metric.
• limit int - Configured limit for the caller’s organization.
• retry_after_seconds int - Seconds to wait before retrying.

​

SandboxSecret

@_attrs_define
class SandboxSecret()

• id str | Unset - The secret id.
• name str | Unset - The human-readable secret name — unique within the organization. The sandbox spec references it by name.
• dest_host str | Unset - Exact public HTTPS host to which proof-bound delivery is bound. Empty for sandbox- environment delivery, which is bound to an authorized sandbox execution instead of a network destination.
• current_version str | Unset - The current version number. Starts at 1 and increments on each rotation.
• created_at str | Unset - When the secret was created (RFC 3339).
• rotated_at str | Unset - When the secret was last rotated, if ever (RFC 3339).
• expires_at str | Unset - When the secret expires, if an expiry is set (RFC 3339).
• revoked_at str | Unset - When the secret was revoked, if it has been (RFC 3339). A revoked secret cannot be delivered.
• delivery SandboxSecretDelivery | Unset - The only trusted data plane allowed to release this secret.

​

SandboxSecretBinding

@_attrs_define
class SandboxSecretBinding()

• name str - The registered secret name. Admission binds its exact proof-bound destination and use grant.

​

SandboxSecretGrant

@_attrs_define
class SandboxSecretGrant()

• secret_id str | Unset - The granted secret id.
• subject_kind SandboxSecretGrantSubjectKind | Unset - The principal kind.
• subject_id str | Unset - The principal’s immutable id within subject_kind.

​

SandboxServiceListSandboxesMetadata

@_attrs_define
class SandboxServiceListSandboxesMetadata()

​

SandboxSharedFilesystemMount

@_attrs_define
class SandboxSharedFilesystemMount()

• filesystem_id str | Unset - Deployment-registered filesystem id.
• subdirectory str | Unset - Existing relative directory within the filesystem to mount. The directory must already exist when the sandbox pod starts.
• target_path str | Unset - Guest path at which the selected directory is mounted. It is either /workspace, which moves the sandbox’s private durable workspace to /private, or a normalized path below /mnt, which leaves the private workspace at /workspace. Other paths are refused so shared storage cannot replace image executables, configuration, or platform-owned mounts.

​

SandboxSnapshot

@_attrs_define
class SandboxSnapshot()

• id str - The stable snapshot id.
• source_sandbox_id str - The sandbox whose state this snapshot records.
• lineage_path str - The source sandbox’s immutable lineage_path. A child created from this snapshot appends its id to this value, making snapshot parentage the derivation source for sandbox lineage.
• durability SandboxSnapshotDurability - The strongest durability currently confirmed for this snapshot.
• created_at datetime.datetime - When the snapshot was created, in RFC 3339 form.
• image str - The workload image behind this snapshot’s lineage: the root sandbox’s OCI image reference, inherited by every child sandbox created from this snapshot.
• name str | Unset - Optional human-readable name supplied when the snapshot was created.
• parent_snapshot_id str | Unset - The snapshot from which the source sandbox was created. Omitted for an image- created root.

​

SandboxSshConnection

@_attrs_define
class SandboxSshConnection()

• host str - The session-plane hostname.
• port int - The session-plane TCP port.
• user str - The SSH username assigned to the sandbox session.

​

SandboxStateReason

@_attrs_define
class SandboxStateReason()

• code str - Stable machine-readable reason code in snake_case.
• message str - Human-readable detail; clients must not parse it.

​

SandboxVolumeMount

@_attrs_define
class SandboxVolumeMount()

• volume_id str - The volume id to mount. Its current immutable version is pinned at admission.
• target_path str - The absolute path at which the volume is mounted inside the sandbox.

​

SetWorkloadLaunchAclRequest

@_attrs_define
class SetWorkloadLaunchAclRequest()

• name str | Unset - The registered workload name.
• acl WorkloadLaunchAcl | Unset - A per-workload launch ACL: which principals may launch a run or sandbox as the workload.

​

SetWorkloadLaunchAclResponse

@_attrs_define
class SetWorkloadLaunchAclResponse()

• workload Workload | Unset - A registered workload identity, scoped to the caller’s organization.

​

SkippedAnnotation

@_attrs_define
class SkippedAnnotation()

• event_id str | Unset - The stored event_id of the row that failed to decode.
• reason str | Unset - Why the row could not be decoded.

​

StartRunRequest

@_attrs_define
class StartRunRequest()

• project_id str | Unset - The project the new run belongs to.
• parent_run_id str | Unset - Optional parent run to continue the tree from. Empty starts a new tree root.
• label str | Unset - An optional human-readable label.
• execute_as_workload str | Unset - Optional registered workload name to run as. When set, the run is attributed to that workload (the caller must hold launch rights on it and the name must be registered); when empty, the run executes as the caller’s own identity. The executing identity is always declared here, never inferred from the command.

​

StartRunResponse

@_attrs_define
class StartRunResponse()

• run Run | Unset - A run record (the subset the API returns). Intentionally carries no cost or spend roll-up: the product is generic and does not surface cost by default.

​

StartVolumePushRequest

@_attrs_define
class StartVolumePushRequest()

• volume_id str | Unset - The volume to push a new version to.

​

StartVolumePushResponse

@_attrs_define
class StartVolumePushResponse()

• push_id str | Unset - The push handle. Pass it to PublishVolumeVersion once the manifest and all content blobs are uploaded.
• manifest_upload_url str | Unset - Short-lived pre-authorized URL to PUT the manifest (the JSON file listing: per file its path, mode, size, content digest, and chunk list) to. The URL is bound to this push’s staging location; the request needs no additional credentials.
• expires_in_seconds int | Unset - How long the upload URL stays valid, in seconds.
• max_manifest_bytes str | Unset - The largest manifest the server accepts for this push, in bytes.

​

UngrantSandboxSecretResponse

@_attrs_define
class UngrantSandboxSecretResponse()

​

UpdateProjectRequest

@_attrs_define
class UpdateProjectRequest()

• id str | Unset - The project id to update.
• name str | Unset - The new human-readable name (the slug is immutable). Omitted leaves the name unchanged.
• description str | Unset - The new free-text description (at most 4 KiB). An empty value clears it; omitted leaves it unchanged.

​

UpdateProjectResponse

@_attrs_define
class UpdateProjectResponse()

• project Project | Unset - A project record (the subset the API returns).

​

UpdateSandboxIdleTimeoutRequest

@_attrs_define
class UpdateSandboxIdleTimeoutRequest()

• idle_timeout_seconds int - New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged.
• state UpdateSandboxIdleTimeoutRequestState | Unset - New desired lifecycle state. Omit it to leave lifecycle state unchanged.
• ttl_seconds int | Unset - New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid.
• metadata UpdateSandboxIdleTimeoutRequestMetadata | Unset - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.

​

UpdateSandboxIdleTimeoutRequestMetadata

@_attrs_define
class UpdateSandboxIdleTimeoutRequestMetadata()

​

UpdateSandboxMetadataRequest

@_attrs_define
class UpdateSandboxMetadataRequest()

• metadata UpdateSandboxMetadataRequestMetadata - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.
• state UpdateSandboxMetadataRequestState | Unset - New desired lifecycle state. Omit it to leave lifecycle state unchanged.
• ttl_seconds int | Unset - New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid.
• idle_timeout_seconds int | Unset - New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged.

​

UpdateSandboxMetadataRequestMetadata

@_attrs_define
class UpdateSandboxMetadataRequestMetadata()

​

UpdateSandboxNetworkAccessRequest

@_attrs_define
class UpdateSandboxNetworkAccessRequest()

• network_access UpdateSandboxNetworkAccessRequestNetworkAccess - Replacement outbound-network posture. It must be the only update field and returns only after the deployment’s policy controller selects the exact live pod incarnation.

​

UpdateSandboxResponse

@_attrs_define
class UpdateSandboxResponse()

• id str - The sandbox id whose update was accepted.
• request_state UpdateSandboxResponseRequestState - The accepted mutation-request state, distinct from observed sandbox lifecycle state.
• network_access_receipt SandboxNetworkAccessReceipt | Unset - Synchronous observation that policy objects select the exact live pod incarnation. This is not dataplane enforcement proof; phase-sensitive clients probe the network after it.

​

UpdateSandboxStateRequest

@_attrs_define
class UpdateSandboxStateRequest()

• state UpdateSandboxStateRequestState - New desired lifecycle state. Omit it to leave lifecycle state unchanged.
• ttl_seconds int | Unset - New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid.
• metadata UpdateSandboxStateRequestMetadata | Unset - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.
• idle_timeout_seconds int | Unset - New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged.

​

UpdateSandboxStateRequestMetadata

@_attrs_define
class UpdateSandboxStateRequestMetadata()

​

UpdateSandboxTtlRequest

@_attrs_define
class UpdateSandboxTtlRequest()

• ttl_seconds int - New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid.
• state UpdateSandboxTtlRequestState | Unset - New desired lifecycle state. Omit it to leave lifecycle state unchanged.
• metadata UpdateSandboxTtlRequestMetadata | Unset - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.
• idle_timeout_seconds int | Unset - New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged.

​

UpdateSandboxTtlRequestMetadata

@_attrs_define
class UpdateSandboxTtlRequestMetadata()

​

UpdateSandboxWorkspaceRequest

@_attrs_define
class UpdateSandboxWorkspaceRequest()

• workspace_capacity_gib int - New durable workspace capacity in whole GiB. It must be at least the current capacity; shrinking a workspace is unsupported.

​

UsageSnapshot

@_attrs_define
class UsageSnapshot()

• limits list[QuotaLimit] | Unset - Every configured product quota.

​

Volume

@_attrs_define
class Volume()

• id str | Unset - The volume id.
• project_id str | Unset - The project the volume belongs to.
• name str | Unset - The volume name — unique within its project. Limited to letters, digits, dots, dashes, and underscores (at most 100 characters).
• description str | Unset - User-assigned free-text description (at most 4 KiB). Empty when unset.
• quota_bytes str | Unset - Storage quota in bytes: the cap on the volume’s total committed size. A quota, not an allocation — an empty volume consumes no storage.
• current_version_digest str | Unset - Digest of the volume’s current (latest committed) version. Empty until the first push publishes a version.
• created_by str | Unset - Stable id of the principal that created the volume — the API key (or user) that performed the create, recorded server-side. Resolve it to a display name via the principals listing.
• created_at str | Unset - When the volume was created (RFC 3339).
• updated_at str | Unset - When the volume record was last updated (RFC 3339). Equal to created_at until the first update.
• used_bytes str | Unset - Committed storage in bytes: the total size of the distinct content blobs referenced by the volume’s versions. Content is stored deduplicated, so a blob shared by several versions counts once — this is what the volume’s committed content occupies, not the sum of its versions’ sizes. Zero for a volume with no committed versions.

​

VolumeBlobRef

@_attrs_define
class VolumeBlobRef()

• digest str | Unset - The blob’s content digest (blake3:<hex>).
• size_bytes str | Unset - The blob’s exact size in bytes. Verified against the stored object before a version referencing the blob can be published.

​

VolumeBlobUpload

@_attrs_define
class VolumeBlobUpload()

• digest str | Unset - The blob’s content digest, echoed from the request.
• present bool | Unset - True when the blob already exists in the volume store — skip the upload; content is deduplicated by digest.
• upload_url str | Unset - Short-lived pre-authorized URL to PUT the blob’s bytes to. Empty when present is true. The URL is bound to the blob’s content-addressed location; the request needs no additional credentials.

​

VolumeVersion

@_attrs_define
class VolumeVersion()

• volume_id str | Unset - The volume this version belongs to.
• version_digest str | Unset - The version’s identity: the digest of its manifest (blake3:<hex>).
• parent_version_digest str | Unset - The digest of the version this one was published on top of. Empty for a volume’s first version.
• size_bytes str | Unset - Total content size in bytes across all files in the version.
• file_count str | Unset - Number of files in the version.
• created_by str | Unset - Stable id of the principal that published the version, recorded server-side.
• created_at str | Unset - When the version was published (RFC 3339).

​

WhoAmIResponse

@_attrs_define
class WhoAmIResponse()

• principal Principal | Unset - The acting principal, as resolved from the caller’s credential by the API edge. The API trusts the edge-resolved identity; it does not re-authenticate.
• organization OrgRef | Unset - The organization the caller acts in.

​

Workload

@_attrs_define
class Workload()

• id str | Unset - The workload’s stable id.
• name str | Unset - The workload’s registered name — unique within the organization, and how the workload is displayed in attribution everywhere. Lowercase letters, digits, ., _, and -; must start and end with a letter or digit; at most 100 characters.
• description str | Unset - A free-text description of what the workload is for. May be empty.
• launch_acl WorkloadLaunchAcl | Unset - A per-workload launch ACL: which principals may launch a run or sandbox as the workload.
• created_by str | Unset - Stable id of the principal that registered the workload, when recorded.
• created_at str | Unset - When the workload was registered (RFC 3339).
• updated_at str | Unset - When the workload’s registration or ACL was last changed (RFC 3339).
• federation_configs list[WorkloadFederationConfig] | Unset - Live cloud-federation registrations owned by this workload, in creation order.

​

WorkloadFederationConfig

@_attrs_define
class WorkloadFederationConfig()

• id str | Unset - Stable handle used by federation list, remove, and setup.
• workload_id str | Unset - Stable id of the workload that owns this registration.
• cloud str | Unset - Cloud provider: aws, gcp, or azure.
• audience str | Unset - Exact provider audience admitted for this workload.
• descriptor WorkloadFederationDescriptor | Unset - Cloud-specific parameters for one workload federation registration. Only the fields belonging to the selected cloud may be set. AWS requires role_arn and defaults an empty region to us-east-1. Google Cloud requires project_id, project_number, pool_id, and provider_id; service_account_email is optional. Microsoft Entra requires application_id and entra_tenant_id.
• created_by str | Unset - Stable id of the principal that created the registration, when recorded.
• created_at str | Unset - When the registration was created (RFC 3339).

​

WorkloadFederationDescriptor

@_attrs_define
class WorkloadFederationDescriptor()

• role_arn str | Unset - AWS IAM role trusted by this workload.
• region str | Unset - AWS region used by the generated SDK configuration. Defaults to us-east-1.
• project_id str | Unset - Google Cloud project id.
• project_number str | Unset - Google Cloud project number.
• pool_id str | Unset - Google Cloud workload identity pool id.
• provider_id str | Unset - Google Cloud workload identity provider id.
• service_account_email str | Unset - Optional Google Cloud service account to impersonate.
• application_id str | Unset - Microsoft Entra application (client) id.
• entra_tenant_id str | Unset - Microsoft Entra tenant id.

​

WorkloadLaunchAcl

@_attrs_define
class WorkloadLaunchAcl()

• policy WorkloadLaunchAclPolicy | Unset - The launch policy: open to all org members, or restricted to the listed launchers.
• launchers list[WorkloadLauncher] | Unset - The principals allowed to launch as this workload. Meaningful only when the policy is WORKLOAD_LAUNCH_POLICY_RESTRICTED; empty otherwise.

​

WorkloadLauncher

@_attrs_define
class WorkloadLauncher()

• kind str | Unset - The kind of principal this entry names: user (an org member, named by user id — also the meaning of an unset kind) or service_account (a service-account API key, named by key id). Any other value is rejected.
• principal_id str | Unset - The principal’s stable id: a user id for user, a service-account key id for service_account.