> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt > Use this file to discover all available pages before exploring further. # Get an operation status > Returns the status of an operation. For an EXECUTING INSTANCE operation, pass `?inflight=1` to also synthesize the partial `result.stdout` / `result.stderr` from the live event log. Off by default — each fetch with `inflight` triggers an extra subscribe RPC to the guest and drains its current events.gz, which is wasted work for clients that only poll for status transitions. ## OpenAPI ````yaml https://eu-north.nebius.computer/static/api.yaml get /operations/{operationId} openapi: 3.0.0 info: title: Contree API description: > Contree is a container management system combining virtual machine isolation with container operational efficiency. Designed for security-sensitive workloads requiring hardware-enforced boundaries while maintaining container workflow compatibility. version: 1.0.0 servers: - url: '{baseUrl}/v1' description: | Nebius IAM-fronted endpoint (use `IAMBearerAuth` + `IAMProjectHeader`). Override `baseUrl` to point at a different deployment. variables: baseUrl: default: https://api.tokenfactory.nebius.com/sandboxes description: | Base URL of the contree service. Defaults to the public Nebius IAM-fronted endpoint; set to your self-hosted contree origin (e.g. `https://contree.example.com`) when running elsewhere. security: - IAMBearerAuth: [] IAMProjectHeader: [] tags: - name: images description: Operations related to container images - name: files description: Operations related to file uploads - name: instances description: Operations related to container instances - name: inspect description: Operations related to inspecting container images - name: operations description: Operations related to long-running operations - name: auth description: Authentication and token introspection paths: /operations/{operationId}: get: tags: - operations summary: Get an operation status description: | Returns the status of an operation. For an EXECUTING INSTANCE operation, pass `?inflight=1` to also synthesize the partial `result.stdout` / `result.stderr` from the live event log. Off by default — each fetch with `inflight` triggers an extra subscribe RPC to the guest and drains its current events.gz, which is wasted work for clients that only poll for status transitions. operationId: getOperationStatus parameters: - name: operationId in: path required: true description: The ID of the operation schema: $ref: '#/components/schemas/UUIDSchema' - name: inflight in: query required: false allowEmptyValue: true description: | HTTP-flag boolean. Present without a value (`?inflight`) and `?inflight=1` both enable; `?inflight=0` and absence disable. When enabled and the operation is EXECUTING INSTANCE, partial stdout/stderr is synthesized from the live event log and attached under `result`. schema: type: string enum: - '' - '0' - '1' default: '0' responses: '200': description: OK headers: Retry-After: schema: type: integer description: Recommended time in seconds to wait before the next status check content: application/json: schema: $ref: '#/components/schemas/OperationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: UUIDSchema: type: string format: uuid description: A UUID string example: 12345678-9abc-baba-deda-0123456789ab OperationResponse: type: object properties: uuid: $ref: '#/components/schemas/UUIDSchema' kind: type: string description: Type of the operation enum: - image_import - instance status: type: string enum: - PENDING - ASSIGNED - EXECUTING - SUCCESS - FAILED - CANCELLED error: type: string nullable: true created_at: type: string description: ISO 8601 formatted timestamp when the operation was created example: '2024-01-01T12:00:00+00:00' duration: type: number nullable: true image_size: type: integer nullable: true description: > Bytes written for the resulting image/layer(s). `null` when not measured (e.g. disposable instance, non-SUCCESS operations). consumed_cpu: type: number nullable: true description: > CPU seconds (user_cpu_time + system_cpu_time) reported by the in-VM init. `null` when not measured. consumed_memory: type: integer nullable: true description: > Peak memory (max_rss) reported by the in-VM init; units preserved as reported by getrusage. `null` when not measured. image_uuid: nullable: true allOf: - $ref: '#/components/schemas/UUIDSchema' description: | UUID of the source image this operation was run on. Set for INSTANCE operations, `null` for IMAGE_IMPORT. result_image_uuid: nullable: true allOf: - $ref: '#/components/schemas/UUIDSchema' description: | UUID of the image produced by this operation. Only set for completed (SUCCESS) operations, `null` otherwise. metadata: $ref: '#/components/schemas/OperationMetadata' result: type: object description: Result of the operation, if any properties: image: nullable: true allOf: - $ref: '#/components/schemas/UUIDSchema' tag: type: string nullable: true description: Tag assigned to the imported image example: busybox:latest OperationMetadata: oneOf: - $ref: '#/components/schemas/OperationInstanceMetadata' - $ref: '#/components/schemas/ImageImportMetadata' description: Metadata specific to the operation type Error: type: object required: - error properties: error: oneOf: - type: string - type: object - type: array items: type: object description: Error message or structured validation errors example: Some error occurred, this is an example of error message status: type: integer description: HTTP status code example: 500 traceback: type: array items: type: string OperationInstanceMetadata: allOf: - $ref: '#/components/schemas/InstanceSpawnRequest' - type: object description: >- Metadata for an instance execution operation, including request parameters and result properties: image: $ref: '#/components/schemas/UUIDSchema' result: $ref: '#/components/schemas/InstanceResult' ImageImportMetadata: type: object properties: registry: type: object properties: url: type: string description: URL of the container registry example: docker://docker.io/busybox:latest credentials: type: object properties: username: type: string description: Username for the registry authentication example: myuser password: type: string description: Always masked in the response is present example: tag: type: string nullable: true timeout: type: integer description: Maximum time in seconds to wait for the import operation to complete default: 300 example: 300 InstanceSpawnRequest: type: object required: - command - image properties: command: type: string description: > The command to execute. In case if `shell` is set to `true`, this MUST contain shell expression. For example `echo hello world` or `ls -l /app`. If `shell` is set to `false`, this must be a relative or absolute path to the executable inside the image rootfs. For example: `/bin/app` or `/usr/bin/find`. Do not forget pass necessary `PATH` variable to env field, by default `PATH` is set to `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`. example: /bin/app disposable: type: boolean description: >- Creates a disposable execution environment no any state will be saved. default: false hostname: type: string description: Hostname to set when execution. example: container-name default: linuxkit image: $ref: '#/components/schemas/ImageSource' args: type: array items: type: string description: | Arguments to pass to the command if shell is set to false. example: - arg1 - arg2 default: [] shell: type: boolean description: > Whether to run the command through a shell. If `true`, the command must be a shell expression and all values from args will be ignored. If `false`, the command field must be a path to an executable and args will be used. When `true`, environment variables from the image are automatically inherited. When `false`, they are not - use the `env` field to pass them explicitly. default: false env: nullable: true type: object additionalProperties: type: string description: > Environment variables to set in the container. These are merged with image-defined variables when `shell` is `true`. When `shell` is `false`, only variables specified here are available - image-defined variables are not inherited. example: KEY1: value1 KEY2: value2 preserve_env: type: boolean description: > Preserve environment variables in resulting image after execution. When `true`, the image's existing environment variables from `metadata/env` are merged with user-provided `env` values (user values take priority on conflicts), and the combined result is written back to `metadata/env` after command execution. Setting a variable to an empty string or `null` removes it from the preserved environment. default: false cwd: type: string pattern: ^((/[^/]*)+/?)?$ description: > Path to the working directory, must be absolute or a special value the empty string. It means the default working directory of the image or server default will be used. If field is omitted it will be set to the empty string. The directory will be created automatically if it does not exist. example: /app default: '' uid: type: integer minimum: 0 description: User ID to run the process as. example: 0 default: 0 gid: type: integer minimum: 0 description: Group ID to run the process as. example: 0 default: 0 resources_limits: $ref: '#/components/schemas/InstanceResourcesLimits' stdin: $ref: '#/components/schemas/StreamRepr' timeout: type: integer description: Maximum execution time in seconds example: 60 truncate_output_at: type: integer description: > Maximum number of bytes to keep from stdout/stderr. Default is `1048576` (1 MiB). The maximum value is `10485760` (10 MiB). example: 65535 default: 1048576 files: type: object description: Map of absolute file paths to file metadata additionalProperties: type: object properties: uuid: $ref: '#/components/schemas/UUIDSchema' uid: type: integer description: User ID example: 0 gid: type: integer description: Group ID example: 0 mode: type: string description: File mode in octal format (e.g., "0644") example: '0644' example: /root/hello.txt: uuid: a9165a5d-5c86-4bd8-8ee4-ae46c19cf45d uid: 0 gid: 0 mode: '0644' /tmp/log.txt: uuid: 065def2a-e977-4852-8b26-a0ec05e85a90 uid: 1000 gid: 1000 mode: '0600' InstanceResult: type: object description: Result of an instance execution properties: resources: type: object properties: block_input: type: integer description: Block input operations block_output: type: integer description: Block output operations cost: type: number format: float description: Operation cost elapsed_time: type: number description: Elapsed wall time involuntary_switches: type: integer description: Number of involuntary context switches max_rss: type: integer description: Maximum resident set size in KB monotonic_time: type: number format: float description: Monotonic time measurement page_faults: type: integer description: Number of page faults page_faults_io: type: integer description: Number of page faults requiring I/O shared_memory: type: integer description: Shared memory size signals: type: integer description: Number of signals received swaps: type: integer description: Number of swaps system_cpu_time: type: number format: float description: System CPU time used unshared_memory: type: integer description: Unshared memory size user_cpu_time: type: number format: float description: User CPU time used voluntary_switches: type: integer description: Number of voluntary context switches state: type: object properties: continued: type: boolean description: Whether the process was continued from a stop core_dump: type: boolean description: Whether a core dump was generated exit_code: type: integer description: Process exit code pid: type: integer description: Process ID signal: type: integer description: Signal that caused termination, if any stopped: type: boolean description: Whether the process was stopped timed_out: type: boolean description: >- Whether process had been killed because operation timeout was reached stdout: $ref: '#/components/schemas/StreamRepr' stderr: $ref: '#/components/schemas/StreamRepr' ImageSource: oneOf: - $ref: '#/components/schemas/UUIDSchema' - $ref: '#/components/schemas/ImageSourceTag' description: > An base image for run a new instance. May be either image UUID or image tag (prefixed with "tag:"). After creation of the instance, if tag is used, this value will be resolved to the image UUID, and the UUID will be stored in the metadata. example: tag:busybox:latest InstanceResourcesLimits: type: object properties: max_layer_bytes: type: integer minimum: 1 description: Maximum writable layer size in bytes. example: 1073741824 default: 12884901888 StreamRepr: type: object required: - value - encoding properties: value: type: string description: Content of the stream example: Y29tbWFuZCBvdXRwdXQK encoding: type: string enum: - ascii - base64 description: Encoding of the content example: base64 truncated: type: boolean description: Whether the output was truncated example: false ImageSourceTag: type: string description: > A container image tag. String must be started with a prefix "tag:" followed by the actual tag. pattern: ^tag:[A-Za-z0-9][A-Za-z0-9_-]*(?:[:/.][A-Za-z0-9_-]+)*$ example: tag:busybox:latest responses: BadRequest: description: Bad Request - Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: | Unauthorized - Invalid or missing authentication credentials. Either the `Authorization` bearer token is missing or invalid, or the `Project` header is missing. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden - Token does not have sufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not Found - The requested resource does not exist content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: IAMBearerAuth: type: http scheme: bearer bearerFormat: IAM description: | IAM bearer token issued by the Nebius IAM service. Sent as `Authorization: Bearer `. Must be combined with the `Project` header (see `IAMProjectHeader`). This is the recommended authentication scheme for new clients. IAMProjectHeader: type: apiKey in: header name: Project description: | Nebius project ID associated with the IAM token. Required together with `IAMBearerAuth`. Identifies the project context the request is scoped to. ````