Skip to main content
POST
List sessions

Restrictions

Usage

  • Pagination uses p/limit (default 20, max 100). The caller’s pinned sessions that match the filters are prepended on page 1 in addition to limit rows, never appear on later pages, and are not counted in total.
  • scope=all returns sessions the caller created plus sessions bound to teams the caller belongs to. Membership is real team membership for every role; account owners and admins do not see other teams’ sessions here.
  • team_ids, person_ids, and entry_kinds only narrow the visible set. Incognito sessions are never listed; subagent sessions appear only with include_subagent_sessions=true.
  • creator_name, has_unread, and pinned_at are computed per caller. The current_turn_* fields and context_window are always 0, and state, bound_environment, context_resolved, automation, and has_open_tasks are not returned; use POST /safari/session/get for them.

Authorizations

app_key
string
query
required

APP Key created in the Flashduty console under My → APP Key. Send it as the app_key query parameter or in the Fd-App-Key request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.

Body

application/json

Filters for listing agent sessions. all visibility means the caller's own personal sessions plus accessible team sessions; account admins do not see other users' personal sessions.

app_name
enum<string>
required

Agent app whose sessions to list. One of:

Available options:
ask-ai,
support,
support-website,
support-flashcat,
ai-sre,
template-assistant,
query-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: created_at by creation time, updated_at by last update; defaults to updated_at when omitted.

Available options:
created_at,
updated_at
asc
boolean

Ascending order when true, descending when false. Only honored together with orderby; when orderby is omitted the sort is always updated_at descending.

include_subagent_sessions
boolean

When true, also list child sessions spawned by subagent dispatch. Defaults to false (top-level sessions only).

keyword
string

Return only sessions whose session_name contains this text; leading and trailing spaces are ignored.

Maximum string length: 64
scope
enum<string>

Visibility scope:

  • all (default): sessions the caller created plus sessions bound to teams the caller belongs to
  • personal: the caller's own sessions with no team (team_id = 0)
  • team: sessions bound to teams the caller belongs to; empty when the caller is in no team
Available options:
all,
personal,
team
team_ids
integer<int64>[]

Optional explicit team filter; intersects with scope and never expands access.

person_ids
integer<int64>[]

Filter by who started the session: returns only sessions started by these members (a session is kept when person_id matches any of them). Intersects with scope and team_ids, so it never widens what the caller is allowed to see.

entry_kinds
enum<string>[]

Restrict to sessions created from these surfaces: web (console), im (IM bot or IM H5), api (public API), automation (automation rule). Empty returns every kind.

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

Archive filter:

  • active (default): sessions that are not archived
  • archived: archived sessions only
  • all: 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.