Get a mutation's known outcome

curl --request GET \
  --url https://api.boxrouter.ai/api/v1/operations/{operation_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.boxrouter.ai/api/v1/operations/{operation_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.boxrouter.ai/api/v1/operations/{operation_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.boxrouter.ai/api/v1/operations/{operation_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.boxrouter.ai/api/v1/operations/{operation_id}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "<string>",
  "operation": "<string>",
  "outcome": "not_started",
  "observed_at": "2023-11-07T05:31:56Z",
  "sandbox_id": "<string>",
  "settled_by": "wait_timeout",
  "native_resource_id": "<string>",
  "route": {
    "provider": "<string>",
    "account_id": "<string>",
    "supply": "<string>",
    "selection": {
      "ranked_by": "<string>",
      "attempts": [
        {
          "provider": "<string>",
          "outcome": "completed",
          "native_code": "<string>",
          "native_status": 123,
          "route_id": "<string>",
          "account_id": "<string>",
          "supply": "<string>",
          "cause": "key_rejected"
        }
      ],
      "preparation_skips": [
        {
          "provider": "<string>",
          "reason_code": "<string>",
          "route_id": "<string>",
          "account_id": "<string>",
          "cause": "key_rejected"
        }
      ],
      "fallbacks_allowed": true,
      "stopped_reason": "fallbacks_disabled"
    }
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

Operations

Get a Mutation's Known Outcome

Read the workspace-owned mutation record identified in an error response. This lookup never repeats the mutation. Unknown remains unknown until reconciliation establishes an outcome.

If a creation response was lost, explicitly resubmitting POST /sandboxes in the original workspace with the original Idempotency-Key and identical effective request body recovers a retained creation record. Completed creation returns the original sandbox or an error retaining its operation ID if observing the sandbox’s current state fails. An unresolved record returns 409 with its operation ID without dispatching creation again. Different input returns 409. This POST can create a sandbox if no record exists; it is not a read-only lookup. Unknown records remain until resolved; completed records remain for at least 24 hours. Without the original key and request, or beyond guaranteed retention, inspect owned resources or use support before creating more work. Never change the key to bypass uncertainty.

Get a mutation's known outcome

curl --request GET \
  --url https://api.boxrouter.ai/api/v1/operations/{operation_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.boxrouter.ai/api/v1/operations/{operation_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.boxrouter.ai/api/v1/operations/{operation_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.boxrouter.ai/api/v1/operations/{operation_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.boxrouter.ai/api/v1/operations/{operation_id}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "<string>",
  "operation": "<string>",
  "outcome": "not_started",
  "observed_at": "2023-11-07T05:31:56Z",
  "sandbox_id": "<string>",
  "settled_by": "wait_timeout",
  "native_resource_id": "<string>",
  "route": {
    "provider": "<string>",
    "account_id": "<string>",
    "supply": "<string>",
    "selection": {
      "ranked_by": "<string>",
      "attempts": [
        {
          "provider": "<string>",
          "outcome": "completed",
          "native_code": "<string>",
          "native_status": 123,
          "route_id": "<string>",
          "account_id": "<string>",
          "supply": "<string>",
          "cause": "key_rejected"
        }
      ],
      "preparation_skips": [
        {
          "provider": "<string>",
          "reason_code": "<string>",
          "route_id": "<string>",
          "account_id": "<string>",
          "cause": "key_rejected"
        }
      ],
      "fallbacks_allowed": true,
      "stopped_reason": "fallbacks_disabled"
    }
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

BoxRouter API key; never an upstream provider key.

Path Parameters

operation_id

string

required

Durable operation identifier returned by BoxRouter.

Minimum string length: 1

Pattern: ^[^\u0000]*$

Response

Last known outcome; no arbitrary upstream response payloads.

Durable record of a mutation's outcome and identifiers. Error detail is returned with the original response and correlated by request_id; it is not stored in this record. Creation operations may include a sanitized route and selection summary. These fields are absent for non-create operations. Attempts may name the public route, account and supply they dispatched; payer and child identifiers, provider messages and credentials are never exposed.

string

required

operation

string

required

OpenAPI operation ID of the attempted mutation.

outcome

enum<string>

required

Available options:

not_started,

completed,

partial,

unknown

observed_at

string<date-time>

required

sandbox_id

string | null

required

Owned BoxRouter resource when established, including recovered creations.

settled_by

enum<string>

Present when BoxRouter settled the operation itself rather than observing its end. wait_timeout: a command's wait ran out, so outcome is completed for BoxRouter's request but the command may still be running at the provider. lifetime_elapsed: a create whose result BoxRouter could never read, closed once the provider's maximum sandbox lifetime had passed; outcome stays unknown because BoxRouter cannot tell whether a sandbox was made, but any sandbox it made has ended, and its cost is unknown. Clients must tolerate values they do not know; absence means the outcome was observed.

Available options:

wait_timeout,

lifetime_elapsed

native_resource_id

string

Recorded opaque handle for the operation's provider-specific resource, when known. Use it only with the original sandbox and the matching native operation family. This identifier does not grant access or prove completion. Credentials are never stored in this field; absence means no handle was recorded.

Minimum string length: 1

route

object

Sanitized selected route for a create operation. Omitted for non-create operations. Contains no payer or child identifiers.

Show child attributes

Overview

Sandboxes

Commands

Processes

Files

Terminals

Previews

Volumes

Images

Operations

Routing Settings

Providers

Price Versions

Agent Catalog

Agent Launches

Launch Runs

Workspace Secrets

Artifacts

GitHub

GitHub Actions

Provider Accounts

Credits and Billing

Spend Limits

Get a Mutation's Known Outcome

Authorizations

Path Parameters

Response