Observe & control

Stop & rollback

Stop execution or restore an earlier Environment state.

On this page

Stop active work

Request Run stop

POST /v1/environments/{environmentId}/sessions/{sessionId}/runs/{runId}/stop

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string · min length 1	Yes	Environment identifier. It must belong to the caller’s account or Project.
`path: sessionId`	string · min length 1	Yes	Existing Session identifier within the named Environment.
`path: runId`	string · min length 1	Yes	Run identifier within the named Environment and, where applicable, Session.

Request example

curl -X POST \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions/$SESSION_ID/runs/$RUN_ID/stop" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

No request body.

Responses

202 Accepted.

Response body `application/json`

Field	Type and constraints	Required	Description
`data`	object · extra fields rejected	Yes	Native task execution, output, file diff and checkpoint state. These states settle independently.
`data.id`	string	Yeswithin data	Resource identifier used to read or manage this resource.
`data.environmentId`	string	Yeswithin data	Environment identifier. It must belong to the caller’s account or Project.
`data.sessionId`	string	Yeswithin data	Existing Session identifier within the named Environment.
`data.environmentSequence`	integer · ≥ -9007199254740991; ≤ 9007199254740991	Yeswithin data	Environment-wide Run ordering across all Sessions; rollback uses this ordering.
`data.model`	string	Yeswithin data	Exact native model ID served by your provider or gateway.
`data.input`	string	Yeswithin data	Instructions supplied to the agent for this task.
`data.files`	array	Yeswithin data	Files associated with this resource; each item is described below.
`data.files[]`	object · extra fields rejected	Yeseach array item	Reference to an existing regular workspace file checked before execution.
`data.files[].path`	string	Yeseach array item	Canonical absolute path inside /workspace. Protected state, Git metadata and symlinks are not accepted file targets.
`data.files[].sha256`	string Validation pattern `^[a-f0-9]{64}$`	Noeach array item	Lowercase hexadecimal SHA-256 digest of the file bytes.
`data.status`	string · values: "queued" \| "running" \| "completed" \| "failed" \| "stopped" \| "reverting" \| "reverted"	Yeswithin data	Current resource state; inspect the allowed values and the operation’s lifecycle notes.
`data.stopRequested`	boolean	Yeswithin data	Whether a client has requested that the native task stop.
`data.output`	string	Nowithin data	Final agent output when available. Content retention may erase this field.
`data.error`	object · extra fields rejected	Nowithin data	Execution failure or transient runtime availability diagnostic. While status is running, platform_runtime_unavailable means observation or preparation is blocked; the original task may still be executing. Reuse this Run instead of submitting it again. The diagnostic clears after successful runtime access. Optional timestamped resource samples may be appended asynchronously; these measurements do not establish the timeout cause or OOM.
`data.error.code`	string	Nowithin data	Stable code identifying an execution failure or transient runtime availability diagnostic.
`data.error.message`	string	Nowithin data	Human-readable failure or availability diagnostic; it does not by itself establish that the original task stopped.
`data.fileDiff`	array	Yeswithin data	Manifest of added, modified and deleted regular workspace files. It does not contain file bytes.
`data.fileDiff[]`	object · extra fields rejected	Yeseach array item	Regular workspace file change with before and after content digests.
`data.fileDiff[].path`	string	Yeseach array item	Canonical absolute path inside /workspace. Protected state, Git metadata and symlinks are not accepted file targets.
`data.fileDiff[].kind`	string · values: "added" \| "modified" \| "deleted"	Yeseach array item	Whether the Run added, modified or deleted the regular file.
`data.fileDiff[].beforeSha256`	string Validation pattern `^[a-f0-9]{64}$`	Noeach array item	Content digest before the Run; absent for a newly added file.
`data.fileDiff[].afterSha256`	string Validation pattern `^[a-f0-9]{64}$`	Noeach array item	Content digest after the Run; absent for a deleted file.
`data.fileDiffStatus`	string · values: "pending" \| "ready" \| "failed"	Yeswithin data	File-diff computation state, separate from execution and checkpoint state.
`data.fileDiffError`	string	Nowithin data	Diagnostic text when file-diff computation fails.
`data.checkpoint`	object · extra fields rejected	Yeswithin data	RootFS checkpoint state and identifier, tracked separately from native execution.
`data.checkpoint.status`	string · values: "pending" \| "ready" \| "failed" \| "skipped"	Yeswithin data	Current resource state; inspect the allowed values and the operation’s lifecycle notes.
`data.checkpoint.snapshotId`	string	Nowithin data	Sandbox0 checkpoint identifier. Use a returned initial or Run checkpoint when pinning a fork.
`data.checkpoint.error`	string	Nowithin data	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`data.createdAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Yeswithin data	Creation time as a UTC date-time string.
`data.startedAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Nowithin data	Execution start time as a UTC date-time string.
`data.finishedAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Nowithin data	Terminal execution time as a UTC date-time string.
`data.steeringEnabled`	boolean	Yeswithin data	Whether this Run supports native steering during execution.
`data.contentDeletedAt`	string · format: date-time	Nowithin data	Platform content was erased; native history and checkpoints remain until Environment deletion.

Example

{
  "data": {
    "id": "",
    "environmentId": "",
    "sessionId": "",
    "environmentSequence": -9007199254740991,
    "model": "",
    "input": "",
    "files": [
      {
        "path": ""
      }
    ],
    "status": "queued",
    "stopRequested": false,
    "fileDiff": [
      {
        "path": "",
        "kind": "added"
      }
    ],
    "fileDiffStatus": "pending",
    "checkpoint": {
      "status": "pending"
    },
    "createdAt": "2026-10-12T01:00:00Z",
    "steeringEnabled": false
  }
}

Error responses

400 Invalid request.

application/json

401 Missing or invalid Platform API token.

application/json

404 Resource not found or outside token scope.

application/json

409 Resource state conflict.

application/json

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Stopping asks the native harness to exit. Files already written remain in the workspace, and external changes are not undone. If the Run finished before the request reached it, it can remain completed. Poll the Run to confirm the outcome; a stop response is not proof of restored files.

Restore an earlier boundary

Roll back a Run and every later Run in its Environment

DELETE /v1/environments/{environmentId}/sessions/{sessionId}/runs/{runId}

Asynchronously stops active work and restores the checkpoint immediately before the selected Run. Discards the selected Run and every later Run across all Sessions in its Environment. The selected Run does not need its own checkpoint; pending or failed checkpoints are skipped. Restores affected native Session histories and preserves token usage, fees and audit records. Does not undo external side effects. Retrying a reverted Run is idempotent.

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string · min length 1	Yes	Environment identifier. It must belong to the caller’s account or Project.
`path: sessionId`	string · min length 1	Yes	Existing Session identifier within the named Environment.
`path: runId`	string · min length 1	Yes	Run identifier within the named Environment and, where applicable, Session.

Request example

curl -X DELETE \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions/$SESSION_ID/runs/$RUN_ID" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

No request body.

Responses

202 Accepted.

Response body `application/json`

Field	Type and constraints	Required	Description
`data`	object · extra fields rejected	Yes	Native task execution, output, file diff and checkpoint state. These states settle independently.
`data.id`	string	Yeswithin data	Resource identifier used to read or manage this resource.
`data.environmentId`	string	Yeswithin data	Environment identifier. It must belong to the caller’s account or Project.
`data.sessionId`	string	Yeswithin data	Existing Session identifier within the named Environment.
`data.environmentSequence`	integer · ≥ -9007199254740991; ≤ 9007199254740991	Yeswithin data	Environment-wide Run ordering across all Sessions; rollback uses this ordering.
`data.model`	string	Yeswithin data	Exact native model ID served by your provider or gateway.
`data.input`	string	Yeswithin data	Instructions supplied to the agent for this task.
`data.files`	array	Yeswithin data	Files associated with this resource; each item is described below.
`data.files[]`	object · extra fields rejected	Yeseach array item	Reference to an existing regular workspace file checked before execution.
`data.files[].path`	string	Yeseach array item	Canonical absolute path inside /workspace. Protected state, Git metadata and symlinks are not accepted file targets.
`data.files[].sha256`	string Validation pattern `^[a-f0-9]{64}$`	Noeach array item	Lowercase hexadecimal SHA-256 digest of the file bytes.
`data.status`	string · values: "queued" \| "running" \| "completed" \| "failed" \| "stopped" \| "reverting" \| "reverted"	Yeswithin data	Current resource state; inspect the allowed values and the operation’s lifecycle notes.
`data.stopRequested`	boolean	Yeswithin data	Whether a client has requested that the native task stop.
`data.output`	string	Nowithin data	Final agent output when available. Content retention may erase this field.
`data.error`	object · extra fields rejected	Nowithin data	Execution failure or transient runtime availability diagnostic. While status is running, platform_runtime_unavailable means observation or preparation is blocked; the original task may still be executing. Reuse this Run instead of submitting it again. The diagnostic clears after successful runtime access. Optional timestamped resource samples may be appended asynchronously; these measurements do not establish the timeout cause or OOM.
`data.error.code`	string	Nowithin data	Stable code identifying an execution failure or transient runtime availability diagnostic.
`data.error.message`	string	Nowithin data	Human-readable failure or availability diagnostic; it does not by itself establish that the original task stopped.
`data.fileDiff`	array	Yeswithin data	Manifest of added, modified and deleted regular workspace files. It does not contain file bytes.
`data.fileDiff[]`	object · extra fields rejected	Yeseach array item	Regular workspace file change with before and after content digests.
`data.fileDiff[].path`	string	Yeseach array item	Canonical absolute path inside /workspace. Protected state, Git metadata and symlinks are not accepted file targets.
`data.fileDiff[].kind`	string · values: "added" \| "modified" \| "deleted"	Yeseach array item	Whether the Run added, modified or deleted the regular file.
`data.fileDiff[].beforeSha256`	string Validation pattern `^[a-f0-9]{64}$`	Noeach array item	Content digest before the Run; absent for a newly added file.
`data.fileDiff[].afterSha256`	string Validation pattern `^[a-f0-9]{64}$`	Noeach array item	Content digest after the Run; absent for a deleted file.
`data.fileDiffStatus`	string · values: "pending" \| "ready" \| "failed"	Yeswithin data	File-diff computation state, separate from execution and checkpoint state.
`data.fileDiffError`	string	Nowithin data	Diagnostic text when file-diff computation fails.
`data.checkpoint`	object · extra fields rejected	Yeswithin data	RootFS checkpoint state and identifier, tracked separately from native execution.
`data.checkpoint.status`	string · values: "pending" \| "ready" \| "failed" \| "skipped"	Yeswithin data	Current resource state; inspect the allowed values and the operation’s lifecycle notes.
`data.checkpoint.snapshotId`	string	Nowithin data	Sandbox0 checkpoint identifier. Use a returned initial or Run checkpoint when pinning a fork.
`data.checkpoint.error`	string	Nowithin data	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`data.createdAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Yeswithin data	Creation time as a UTC date-time string.
`data.startedAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Nowithin data	Execution start time as a UTC date-time string.
`data.finishedAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Nowithin data	Terminal execution time as a UTC date-time string.
`data.steeringEnabled`	boolean	Yeswithin data	Whether this Run supports native steering during execution.
`data.contentDeletedAt`	string · format: date-time	Nowithin data	Platform content was erased; native history and checkpoints remain until Environment deletion.

Example

{
  "data": {
    "id": "",
    "environmentId": "",
    "sessionId": "",
    "environmentSequence": -9007199254740991,
    "model": "",
    "input": "",
    "files": [
      {
        "path": ""
      }
    ],
    "status": "queued",
    "stopRequested": false,
    "fileDiff": [
      {
        "path": "",
        "kind": "added"
      }
    ],
    "fileDiffStatus": "pending",
    "checkpoint": {
      "status": "pending"
    },
    "createdAt": "2026-10-12T01:00:00Z",
    "steeringEnabled": false
  }
}

Error responses

400 Invalid request.

application/json

401 Missing or invalid Platform API token.

application/json

404 Resource not found or outside token scope.

application/json

409 Resource state conflict.

application/json

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Rollback restores the checkpoint immediately before the selected Run. It discards that Run and every later Run across all Sessions in the Environment. Active work stops before restore, and affected native Session histories are restored.

Choose the Run by Environment chronology, not just its Session’s history. For example, rolling back an earlier Session A Run can also discard a later Session B Run that changed the same workspace.

Wait for rollback completion

Rollback is asynchronous. Poll the selected Run until the restore has completed. New Runs and file operations wait during rollback. The selected Run does not need its own checkpoint; pending or failed affected checkpoints become skipped. Retrying a reverted Run does not discard work submitted afterwards.

Get Run state and Sandbox usage

GET /v1/environments/{environmentId}/sessions/{sessionId}/runs/{runId}

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string · min length 1	Yes	Environment identifier. It must belong to the caller’s account or Project.
`path: sessionId`	string · min length 1	Yes	Existing Session identifier within the named Environment.
`path: runId`	string · min length 1	Yes	Run identifier within the named Environment and, where applicable, Session.

Request example

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions/$SESSION_ID/runs/$RUN_ID" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

No request body.

Responses

200 Successful response.

Response body `application/json`

Field	Type and constraints	Required	Description
`data`	object · extra fields rejected	Yes	Run details with posted Sandbox runtime and retained historical managed-model settlement; BYOK model costs are billed by your provider.
`data.id`	string	Yeswithin data	Resource identifier used to read or manage this resource.
`data.environmentId`	string	Yeswithin data	Environment identifier. It must belong to the caller’s account or Project.
`data.sessionId`	string	Yeswithin data	Existing Session identifier within the named Environment.
`data.environmentSequence`	integer · ≥ -9007199254740991; ≤ 9007199254740991	Yeswithin data	Environment-wide Run ordering across all Sessions; rollback uses this ordering.
`data.model`	string	Yeswithin data	Exact native model ID served by your provider or gateway.
`data.input`	string	Yeswithin data	Instructions supplied to the agent for this task.
`data.files`	array	Yeswithin data	Files associated with this resource; each item is described below.
`data.files[]`	object · extra fields rejected	Yeseach array item	Reference to an existing regular workspace file checked before execution.
`data.files[].path`	string	Yeseach array item	Canonical absolute path inside /workspace. Protected state, Git metadata and symlinks are not accepted file targets.
`data.files[].sha256`	string Validation pattern `^[a-f0-9]{64}$`	Noeach array item	Lowercase hexadecimal SHA-256 digest of the file bytes.
`data.status`	string · values: "queued" \| "running" \| "completed" \| "failed" \| "stopped" \| "reverting" \| "reverted"	Yeswithin data	Current resource state; inspect the allowed values and the operation’s lifecycle notes.
`data.stopRequested`	boolean	Yeswithin data	Whether a client has requested that the native task stop.
`data.output`	string	Nowithin data	Final agent output when available. Content retention may erase this field.
`data.fileDiff`	array	Yeswithin data	Manifest of added, modified and deleted regular workspace files. It does not contain file bytes.
`data.fileDiff[]`	object · extra fields rejected	Yeseach array item	Regular workspace file change with before and after content digests.
`data.fileDiff[].path`	string	Yeseach array item	Canonical absolute path inside /workspace. Protected state, Git metadata and symlinks are not accepted file targets.
`data.fileDiff[].kind`	string · values: "added" \| "modified" \| "deleted"	Yeseach array item	Whether the Run added, modified or deleted the regular file.
`data.fileDiff[].beforeSha256`	string Validation pattern `^[a-f0-9]{64}$`	Noeach array item	Content digest before the Run; absent for a newly added file.
`data.fileDiff[].afterSha256`	string Validation pattern `^[a-f0-9]{64}$`	Noeach array item	Content digest after the Run; absent for a deleted file.
`data.fileDiffStatus`	string · values: "pending" \| "ready" \| "failed"	Yeswithin data	File-diff computation state, separate from execution and checkpoint state.
`data.fileDiffError`	string	Nowithin data	Diagnostic text when file-diff computation fails.
`data.checkpoint`	object · extra fields rejected	Yeswithin data	RootFS checkpoint state and identifier, tracked separately from native execution.
`data.checkpoint.status`	string · values: "pending" \| "ready" \| "failed" \| "skipped"	Yeswithin data	Current resource state; inspect the allowed values and the operation’s lifecycle notes.
`data.checkpoint.snapshotId`	string	Nowithin data	Sandbox0 checkpoint identifier. Use a returned initial or Run checkpoint when pinning a fork.
`data.checkpoint.error`	string	Nowithin data	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`data.createdAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Yeswithin data	Creation time as a UTC date-time string.
`data.startedAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Nowithin data	Execution start time as a UTC date-time string.
`data.finishedAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Nowithin data	Terminal execution time as a UTC date-time string.
`data.usage`	object · extra fields rejected	Yeswithin data	Posted Sandbox runtime usage and retained historical managed-model settlement. New BYOK Runs have no rated model-call ledger; provider usage and cost are recorded by the customer’s provider or gateway.
`data.usage.calls`	array	Yeswithin data	Historical rated managed-model calls only. Empty for new BYOK Runs; does not measure native model requests.
`data.usage.calls[]`	object · extra fields rejected	Yeseach array item	—
`data.usage.calls[].id`	string	Yeseach array item	Resource identifier used to read or manage this resource.
`data.usage.calls[].provider`	string · values: "openai" \| "anthropic" \| "kimi" \| "zai" \| "deepseek"	Yeseach array item	Native model family associated with this Harness; not a Sandpi Token supplier.
`data.usage.calls[].model`	string	Yeseach array item	Exact native model ID served by your provider or gateway.
`data.usage.calls[].priceVersion`	string	Yeseach array item	Historical managed-model settlement only. Immutable version of the published price captured for rating.
`data.usage.calls[].priceSourceUrl`	string · format: uri	Yeseach array item	Historical managed-model settlement only. Official provider pricing reference captured with the immutable price version.
`data.usage.calls[].usageCategories`	object	Yeseach array item	Historical managed-model settlement only. Provider-reported usage by category, such as uncached input, cached input and output tokens.
`data.usage.calls[].usageCategories.{key}`	number	Noadditional keys	—
`data.usage.calls[].ratedLines`	array	Yeseach array item	Historical managed-model settlement only. Rated accounting line items for the provider call.
`data.usage.calls[].ratedLines[]`	any	Yeseach array item	—
`data.usage.calls[].upstreamAmountUsd`	string	Yeseach array item	Historical managed-model settlement only. Published base-rate usage amount in USD, represented as a decimal string.
`data.usage.calls[].serviceFeeUsd`	string	Yeseach array item	Historical managed-model settlement only. Itemized service fee in USD, represented as a decimal string.
`data.usage.calls[].totalAmountUsd`	string	Yeseach array item	Historical managed-model settlement only. Total rated charge in USD, represented as a decimal string.
`data.usage.calls[].createdAt`	string · format: date-time Validation pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`	Yeseach array item	Creation time as a UTC date-time string.
`data.usage.calls[].serviceFeePercent`	number · values: 0 \| 5 \| 10 \| 15	Yeseach array item	Historical managed-model settlement only. Service fee captured by this call’s immutable price version; zero for legacy calls.
`data.usage.serviceFeePercent`	number · values: 0 \| 5 \| 10 \| 15 \| null	Yeswithin data	Historical managed-model fee shared by all calls, or null for mixed historical tiers. Zero for new BYOK Runs; Sandpi adds no model service fee.
`data.usage.upstreamAmountUsd`	string	Yeswithin data	Historical managed-model base charges in USD. Zero for new BYOK Runs; excludes charges billed directly by your model provider.
`data.usage.serviceFeeUsd`	string	Yeswithin data	Historical managed-model service fees in USD. Zero for new BYOK Runs.
`data.usage.totalAmountUsd`	string	Yeswithin data	Posted Sandbox runtime plus retained historical managed-model charges in USD. Excludes model charges billed directly by your provider or gateway.
`data.usage.sandboxAmountUsd`	string	Yeswithin data	Posted Sandbox runtime charge attributed to this Run. Environment initialization and file access may incur separate Environment charges.
`data.usage.sandboxRuntimeSeconds`	number · ≥ 0	Nowithin data	Authoritative billed Sandbox time attributed to this Run.

Example

{
  "data": {
    "id": "",
    "environmentId": "",
    "sessionId": "",
    "environmentSequence": -9007199254740991,
    "model": "",
    "input": "",
    "files": [
      {
        "path": ""
      }
    ],
    "status": "queued",
    "stopRequested": false,
    "fileDiff": [
      {
        "path": "",
        "kind": "added"
      }
    ],
    "fileDiffStatus": "pending",
    "checkpoint": {
      "status": "pending"
    },
    "createdAt": "2026-10-12T01:00:00Z",
    "usage": {
      "calls": [],
      "serviceFeePercent": 0,
      "upstreamAmountUsd": "",
      "serviceFeeUsd": "",
      "totalAmountUsd": "",
      "sandboxAmountUsd": ""
    }
  }
}

Error responses

400 Invalid request.

application/json

401 Missing or invalid Platform API token.

application/json

404 Resource not found or outside token scope.

application/json

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Understand the restore boundary

Rollback restores RootFS files and affected native history. It retains Sandbox charges, usage and audit facts, and cannot undo emails, Git pushes or other external side effects. Egress credentials and MCP configuration retain their current versions.

To erase API content or delete a workspace, use retention and deletion. To preserve an independent workspace before further changes, use a fork.

Stop & rollback

Stop active work

Request Run stop

Parameters and headers

Request example

Responses

Response body application/json

Error body application/json

Restore an earlier boundary

Roll back a Run and every later Run in its Environment

Parameters and headers

Request example

Responses

Response body application/json

Error body application/json

Wait for rollback completion

Get Run state and Sandbox usage

Parameters and headers

Request example

Responses

Response body application/json

Error body application/json

Understand the restore boundary

Response body `application/json`

Error body `application/json`

Response body `application/json`

Error body `application/json`

Response body `application/json`

Error body `application/json`