Skip to content
DreadnodeDreadnodeDreadnode

List Sessions

GET
/api/v1/org/{org}/ws/{workspace}/sessions
curl --request GET \
  --url 'https://example.com/api/v1/org/example/ws/example/sessions?archived=active&include_workload_sessions=false&sort_by=last_message_at&sort_dir=asc&pinned_first=false&page=1&limit=20' \
  --header 'Authorization: Bearer <token>'

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.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
org
required
Org

Organization slug

string

Organization slug

workspace
required
Workspace

Workspace slug

string

Workspace slug

Query Parameters

Section titled “Query Parameters”
user_id
Any of:
string format: uuid

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:
Array<string>

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:
Array<string>

Filter by one or more session.agent values. Repeat the param to combine with OR; omit to skip the dimension.

model
Any of:
Array<string>

Filter by one or more session.model values. Repeat the param to combine with OR; omit to skip the dimension.

origin
Any of:
Array<string>

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:
Array<string>

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

Session-state filter. active (default) hides archived sessions, inactive returns unarchived sessions idle past the 15-minute activity window, archived returns only archived, any returns everything.

string
default: active
Allowed values: active inactive archived any

Session-state filter. active (default) hides archived sessions, inactive returns unarchived sessions idle past the 15-minute activity window, archived returns only archived, any returns everything.

label
Any of:
Array<string>

Label filter as key:value; repeat for OR within a key, combine keys for AND (SES-LBL-050/051/052).

search
Any of:
string
<= 200 characters

Free-form search over session title, first-message preview, 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. A session id, or any leading slice of one, matches as a prefix.

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. Analytics or reporting callers pass true to include them; the agents Sessions monitoring list intentionally leaves this false — eval-origin sessions surface under Evaluations, not that list.

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. Analytics or reporting callers pass true to include them; the agents Sessions monitoring list intentionally leaves this false — eval-origin sessions surface under Evaluations, not that list.

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

Sort direction

string
default: desc
Allowed values: asc desc

Sort direction

pinned_first
Pinned First

When true, sessions the caller has pinned sort ahead of the requested order, newest pin first. Pins are per user.

boolean

When true, sessions the caller has pinned sort ahead of the requested order, newest pin first. Pins are per user.

page
Page

Page number

integer
default: 1 >= 1

Page number

limit
Limit

Items per page

integer
default: 20 >= 1 <= 100

Items per page

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
SessionListResponse

Paginated list of sessions.

object
has_next
required
Has Next

Whether a next page exists

boolean
has_previous
required
Has Previous

Whether a previous page exists

boolean
limit
required
Limit

Maximum items per page

integer
page
required
Page

Current page number (1-indexed)

integer
sessions
required
Sessions

List of sessions

Array<object>
SessionResponse

Session response for list and detail views.

object
agent
required
Any of:
string
archived_at
required
Any of:
string format: date-time
created_at
required
Created At
string format: date-time
created_by
Any of:
SessionCreatorResponse

Small denormalized view of a user attached to a session.

Used for both the creator (created_by, from the eager-loaded SessionORM.user) and the sharer (shared_by, from SessionORM.shared_by_user) — the role is carried by the field name, not the type. The user’s id is embedded here alongside their email, so clients render attribution without a follow-up request. Only the creator has a separate raw id on the session (user_id); shared_by.id is the sharer’s only id on the wire.

object
email
required
Email
string
full_name
Any of:
string
id
required
Id
string format: uuid
username
required
Username
string
frozen_at
required
Any of:
string format: date-time
frozen_by
required
Any of:
string
Allowed values: evaluation user
group
Any of:
SessionGroupSummary

Visible rollup for one session group.

object
active_session_count
required
Active Session Count
integer
capability
required
Any of:
string
capability_version
required
Any of:
string
completed_at
required
Any of:
string format: date-time
created_at
required
Created At
string format: date-time
evaluation_id
required
Any of:
string format: uuid
evaluation_item_attempt_id
required
Any of:
string format: uuid
evaluation_item_id
required
Any of:
string format: uuid
id
required
Id
string format: uuid
kind
required
Kind
string
Allowed values: worker_run evaluation_item workflow workflow_run
last_activity_at
required
Any of:
string format: date-time
message_count
required
Message Count
integer
runtime_id
required
Any of:
string format: uuid
session_count
required
Session Count
integer
started_at
required
Any of:
string format: date-time
status
required
Any of:
string
Allowed values: running completed failed cancelled
title
required
Any of:
string
total_tokens
required
Total Tokens
integer
updated_at
required
Updated At
string format: date-time
worker
required
Any of:
string
group_id
required
Any of:
string format: uuid
id
required
Id
string format: uuid
labels
Labels

Labels attached to this session as {key: [value, ...]}.

object
key
additional properties
Array<string>
last_message_at
required
Any of:
string format: date-time
message_count
required
Message Count
integer
model
required
Model
string
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
pinned
Any of:
boolean
preview_text
Any of:
string
project_id
required
Any of:
string format: uuid
project_key
Any of:
string
project_name
required
Any of:
string
recent_message_count
Any of:
integer
<= 25
runtime_id
required
Any of:
string format: uuid
shared_at
Any of:
string format: date-time
shared_by
Any of:
SessionCreatorResponse

Small denormalized view of a user attached to a session.

Used for both the creator (created_by, from the eager-loaded SessionORM.user) and the sharer (shared_by, from SessionORM.shared_by_user) — the role is carried by the field name, not the type. The user’s id is embedded here alongside their email, so clients render attribution without a follow-up request. Only the creator has a separate raw id on the session (user_id); shared_by.id is the sharer’s only id on the wire.

object
email
required
Email
string
full_name
Any of:
string
id
required
Id
string format: uuid
username
required
Username
string
title
required
Any of:
string
updated_at
required
Updated At
string format: date-time
usage
required
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
Compaction Count
integer
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_cost_usd
required
Any of:
number
current_input_tokens
required
Current Input Tokens
integer
current_message_count
required
Current Message Count

Non-compacted message count — the subset the transcript paginates. current means the current era (consistent with the other current_* usage fields), NOT a pagination page; it diverges from total_message_count once the session has been compacted.

integer
current_output_tokens
required
Current Output Tokens
integer
current_tool_call_count
required
Current Tool Call Count
integer
last_generation_input_tokens
required
Any of:
integer
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_cost_usd
required
Any of:
number
total_input_tokens
required
Total Input Tokens
integer
total_message_count
required
Total Message Count

Lifetime message count — every message, compacted included.

integer
total_output_tokens
required
Total Output Tokens
integer
total_tool_call_count
required
Total Tool Call Count
integer
user_id
required
User Id
string format: uuid
visibility
required
Visibility

Discovery visibility only: private means unlisted, workspace means listed. Both are readable with workspace access.

string
Allowed values: private workspace
workspace_id
required
Workspace Id
string format: uuid
total
required
Total

Total items matching the query

integer
total_pages
required
Total Pages

Total number of pages

integer
Example
{
  "sessions": [
    {
      "frozen_by": "evaluation",
      "group": {
        "kind": "worker_run",
        "status": "running"
      },
      "origin": "user",
      "visibility": "private"
    }
  ]
}

400

Section titled “400”

Invalid request

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

401

Section titled “401”

Authentication failed

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

403

Section titled “403”

Access forbidden

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

404

Section titled “404”

Not found

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

409

Section titled “409”

Already exists

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

422

Section titled “422”

Validation error

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

426

Section titled “426”

Upgrade required

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

429

Section titled “429”

Rate limited

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

500

Section titled “500”

Internal server error

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

502

Section titled “502”

Bad gateway

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

504

Section titled “504”

Gateway timeout

Media typeapplication/json
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 task_set_not_found token_error upgrade_required_error usage_limit_exceeded_error user_suspended user_verification_error validation_error
Example
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}