GET
/api/v1/org/{org}/ws/{workspace}/sessions
List sessions for a workspace.
Workspace is the permissions boundary; user_id, project_id,
archived, label, and include_workload_sessions are
filters, not access controls.
user_id
Any of:
Optional user ID to scope to a single session owner. Defaults to all sessions in the workspace; pass the caller’s user id to mimic the chat sidebar’s ‘my sessions’ view.
project_id
Any of:
Filter by one or more project IDs. Repeat the param to pass multiple (?project_id=A&project_id=B); values combine with OR (SES-LST-006). A single ?project_id=A continues to work against the legacy wire shape.
agent
Any of:
Filter by one or more session.agent values. Repeat the param to combine with OR; omit to skip the dimension.
model
Any of:
Filter by one or more session.model values. Repeat the param to combine with OR; omit to skip the dimension.
origin
Any of:
Filter by one or more session.origin values (user/eval/worker, SES-LST-015). Repeat to combine with OR; omit to skip the dimension.
user
Any of:
Filter by one or more session owner user IDs (sessions.user_id). Repeat the param to combine with OR. Use user_id for the legacy single-value shape.
archived
Archived Archived-state filter. active (default) hides archived sessions, archived returns only archived, any returns both.
string
default: active
Allowed values: active archived any
Archived-state filter. active (default) hides archived sessions, archived returns only archived, any returns both.
label
Any of:
Label filter as key:value; repeat for OR within a key, combine keys for AND (SES-LBL-050/051/052).
search
Any of:
Free-form search over session title, model, agent, and label values / key:value pairs (SES-LST-007). Google-style syntax via websearch_to_tsquery; short queries (<3 chars) fall back to substring match.
include_workload_sessions
Include Workload Sessions When false (default), sessions whose origin identifies a platform workload (eval today; optimization, training, world as those writers ship, per SES-ORG-006) are excluded. Pass true on the agents page or analytics callers that want them (SES-LST-009).
boolean
When false (default), sessions whose origin identifies a platform workload (eval today; optimization, training, world as those writers ship, per SES-ORG-006) are excluded. Pass true on the agents page or analytics callers that want them (SES-LST-009).
sort_by
Sort By Column to sort the list by
string
default: updated_at
Allowed values: last_message_at updated_at created_at message_count
Column to sort the list by
sort_dir
Sort Dir string
default: desc
Allowed values: asc desc
page
Page integer
default: 1 >= 1
limit
Limit integer
default: 20 >= 1 <= 100
Select media type application/json SessionListResponse Paginated list of sessions.
object Has Next Whether a next page exists
boolean
Has Previous Whether a previous page exists
boolean
Page Current page number (1-indexed)
integer
Sessions Array<object>
SessionResponse Session response for list and detail views.
object Created At string format: date-time
created_by
Any of:
SessionCreatorResponse Small denormalized view of the session creator for list/detail render.
Included alongside user_id so UI can show an email chip without a
follow-up request. Pulled from the eager-loaded SessionORM.user.
object Any of:
string
Allowed values: evaluation user
labels
Labels Labels attached to this session as {key: [value, ...]}.
object key additional properties
origin
Origin Session origin (SES-ORG-001). user for interactive sessions, eval for evaluation-worker sessions, worker for capability-worker sessions.
string
default: user
Allowed values: user eval worker
Updated At string format: date-time
SessionUsageResponse Aggregated token usage for a session.
All fields are derived at read time from per-message usage columns on
session_messages. Pre-migration sessions (no usage data) report
zeros; new sessions with no inference yet report zeros and
last_generation_input_tokens=None.
object compaction_count required
current_cache_creation_input_tokens required
Current Cache Creation Input Tokens integer
current_cache_read_input_tokens required
Current Cache Read Input Tokens integer
current_input_tokens required
Current Input Tokens integer
current_output_tokens required
Current Output Tokens integer
last_generation_input_tokens required
total_cache_creation_input_tokens required
Total Cache Creation Input Tokens integer
total_cache_read_input_tokens required
Total Cache Read Input Tokens integer
total_input_tokens required
Total Input Tokens integer
total_output_tokens required
Total Output Tokens integer
User Id string format: uuid
Visibility string
Allowed values: private workspace
Workspace Id string format: uuid
Total Total items matching the query
integer
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
Select media type application/json APIErrorPayload Canonical API error envelope returned by the API.
object Code integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
Detail Human-readable error message
string
errors
Any of:
Array<object>
ValidationErrorItem object Loc Where the validation error occurred
Array
Msg Human-readable validation message
string
Type Machine-readable validation error type
string
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
