Skip to main content
POST
List sessions

Restrictions

Usage

  • Pagination uses p/limit (max 100); scope defaults to all (own + member-of-team rows).
  • is_running reflects the live run-set; has_unread is computed per calling user.

Authorizations

app_key
string
query
required

App key issued from the Flashduty console. Required on every public API call. Keep it secret — it grants the same access as the owning account.

Body

application/json

Filters for listing agent sessions. Reads are scoped to the resolved account and the caller's visible teams.

app_name
enum<string>
required

Agent app whose sessions to list.

Available options:
ask-ai,
support,
support-website,
support-flashcat,
ai-sre,
template-assistant,
swe
p
integer
default:1

Page number, 1-based.

Required range: x >= 1
limit
integer
default:20

Page size, 1–100.

Required range: 1 <= x <= 100
orderby
enum<string>

Sort field.

Available options:
created_at,
updated_at
asc
boolean

Ascending order when true; applies only when orderby is set.

include_subagent_sessions
boolean

Include subagent-dispatched sessions in the list.

keyword
string

Filter by session-name keyword.

Maximum string length: 64
scope
enum<string>

Visibility scope: all (own + member-of-team rows, default), personal, or team.

Available options:
all,
personal,
team
team_ids
integer<int64>[]

Optional explicit team filter; intersects with scope.

entry_kinds
enum<string>[]

Restrict to sessions produced by these surfaces; empty returns every kind.

Available options:
web,
im,
api,
automation
status
enum<string>

Archive bucket: active (default) returns un-archived, archived returns archived, all returns both.

Available options:
active,
archived,
all

Response

Success

Standard response envelope used by every Flashduty public API. On success data contains the endpoint-specific payload and error is absent. On failure error is present and data is absent. request_id is always present and is also mirrored in the Flashcat-Request-Id response header.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

error
object

Error payload inside the response envelope. Present only on non-2xx responses.

data
object

A page of agent sessions.