Skip to content

Get sandbox facets

GET
/api/v1/org/{org}/sandboxes/facets

Per-dimension counts for sandboxes the caller can see in this org. Every caller-supplied filter is applied to both facets, so counts reflect the sandboxes currently in view. Powers the tab badges and filter dropdowns on the Hosted Sandboxes page.

org
required
Org

Organization slug

string

Organization slug

state
Any of:
Array<string>

Active sandbox state filter (repeatable or comma-separated). Narrows both the states and projects facets.

project_id
Any of:
string format: uuid

Active project filter. Narrows both facets.

Successful Response

SandboxFacetsResponse

Per-dimension value counts for sandboxes matching the caller’s filter.

Every caller-supplied filter is applied to both facets — counts reflect “what’s in the current view”. Both lists are pre-sorted by count DESC with a stable alphabetical tiebreaker.

object
projects
Projects

Distinct projects with sandbox counts. Sandboxes without a project are omitted because they cannot be selected as project filter options.

Array<object>
SandboxProjectFacetEntry

A single project bucket and its sandbox count.

Sandboxes without a project are omitted from this facet because they cannot be used as project filter options; they are still included in the state facet counts and the sandbox list response.

object
count
required
Count
integer
project_id
Any of:
string format: uuid
project_key
Any of:
string
project_name
Any of:
string
states
States

Distinct sandbox state values with sandbox counts. Empty buckets are omitted.

Array<object>
SandboxStateFacetEntry

A single sandbox state and its count under the caller’s filters.

object
count
required
Count
integer
value
required
Value
string
Allowed values: running paused killed

Invalid request

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Authentication failed

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Access forbidden

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Not found

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Already exists

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Validation error

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Upgrade required

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Rate limited

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Internal server error

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Bad gateway

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error

Gateway timeout

APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error