> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-api-review-auto-fix.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询会话列表

> 分页查询调用者可见的智能体会话，可按应用、入口、归档状态与团队过滤。

## 限制说明

| 项目   | 说明                                     |
| ---- | -------------------------------------- |
| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |
| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用              |

## 使用说明

* 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。
* `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。
* `team_ids` 只会收窄可见集合，不会扩大访问范围。
* `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。
* `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识包时为 true），与列表过滤条件无关。


## OpenAPI

````yaml /api-reference/safari.openapi.zh.json post /safari/session/list
openapi: 3.1.0
info:
  title: Flashduty 开放 API
  description: >-
    Flashduty AI SRE 平台的公开 HTTP API —— 技能、MCP 服务器（连接器）、A2A 智能体与会话。所有接口均使用
    Flashduty 控制台签发的 `app_key` 查询参数进行认证。
  version: 1.0.0
servers:
  - url: https://api.flashcat.cloud
    description: Flashduty Open API
security:
  - AppKeyAuth: []
tags:
  - name: AI SRE/技能
  - name: AI SRE/MCP 服务器
  - name: AI SRE/A2A 智能体
  - name: AI SRE/会话
  - name: AI SRE/自动化
paths:
  /safari/session/list:
    post:
      tags:
        - AI SRE/会话
      summary: 查询会话列表
      description: 分页查询调用者可见的智能体会话，可按应用、入口、归档状态与团队过滤。
      operationId: session-read-list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionListRequest'
            example:
              app_name: ai-sre
              limit: 2
              orderby: updated_at
              scope: all
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/SessionListResponse'
              example:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                data:
                  total: 988
                  sessions:
                    - session_id: sess_f8oDvqiG64uur6sBNsTc4u
                      session_name: Investigate cloud-assistant first heartbeat
                      app_name: ai-sre
                      entry_kind: web
                      person_id: '3790925372131'
                      team_id: 0
                      is_mine: false
                      can_view: true
                      can_continue: true
                      can_manage: true
                      can_fork: true
                      access_source: manager
                      share_enabled: true
                      share_version: 3
                      shared_at: 1780367971000
                      shared_by: 3790925372131
                      status: enabled
                      incognito: false
                      created_at: 1780367971228
                      updated_at: 1780367993457
                      token_usage:
                        input_tokens: 14948
                        cached_tokens: 11520
                        output_tokens: 888
                        reasoning_tokens: 351
                      current_context_tokens: 14948
                      context_window: 0
                      archived_at: 0
                      pinned_at: 0
                      last_event_at: 1780367992649
                      is_running: false
                      has_unread: true
                      current_turn_started_at: 0
                      current_turn_active_ms: 0
                      current_turn_wait_ms: 0
                      current_turn_tokens: 0
                  suggest_init: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - AppKeyAuth: []
components:
  schemas:
    SessionListRequest:
      type: object
      description: 查询智能体会话列表的过滤条件。`all` 表示调用者自己的个人会话和可访问团队的团队会话；账户管理员不可见他人的个人会话。
      properties:
        app_name:
          type: string
          description: 要查询其会话的智能体应用。
          enum:
            - ask-ai
            - support
            - support-website
            - support-flashcat
            - ai-sre
            - template-assistant
            - swe
        p:
          type: integer
          description: 页码，从 1 开始。
          default: 1
          minimum: 1
        limit:
          type: integer
          description: 每页数量，1–100。
          minimum: 1
          maximum: 100
          default: 20
        orderby:
          type: string
          description: 排序字段。
          enum:
            - created_at
            - updated_at
        asc:
          type: boolean
          description: 为 true 时升序；仅在设置 `orderby` 时生效。
        include_subagent_sessions:
          type: boolean
          description: 是否在列表中包含子智能体派生的会话。
        keyword:
          type: string
          description: 按会话名称关键字过滤。
          maxLength: 64
        scope:
          type: string
          description: 可见范围：`all`（自己的个人会话 + 可访问团队会话）、`personal` 或 `team`；默认 `all`。
          enum:
            - all
            - personal
            - team
        team_ids:
          type: array
          items:
            type: integer
            format: int64
          description: 可选的团队过滤；与 `scope` 取交集，且不会扩大访问范围。
        entry_kinds:
          type: array
          items:
            type: string
            enum:
              - web
              - im
              - api
              - automation
          description: 仅返回由这些入口产生的会话；为空则返回所有类型。
        status:
          type: string
          description: 归档分桶：active（默认）返回未归档，archived 返回已归档，all 返回全部。
          enum:
            - active
            - archived
            - all
      required:
        - app_name
    ResponseEnvelope:
      type: object
      description: >-
        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.
      properties:
        request_id:
          type: string
          description: >-
            Unique ID for this request. Mirrored in the Flashcat-Request-Id
            header. Include it when reporting issues.
          example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
        error:
          $ref: '#/components/schemas/DutyError'
        data:
          description: Endpoint-specific payload. See each operation's 200 response schema.
      required:
        - request_id
    SessionListResponse:
      type: object
      description: 一页智能体会话。
      properties:
        total:
          type: integer
          format: int64
          description: 匹配过滤条件的会话总数（忽略分页）。
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/SessionItem'
          description: 当前页的会话。
        suggest_init:
          type: boolean
          description: 账户级引导标志：当账户在任何范围内都没有知识包时为 true；与本次调用的过滤条件无关。
      required:
        - total
        - sessions
        - suggest_init
    DutyError:
      type: object
      description: >-
        Error payload inside the response envelope. Present only on non-2xx
        responses.
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: >-
            Human-readable error message, localized by the caller's
            Accept-Language. May contain field names, IDs, or other context from
            the failing request.
      required:
        - code
        - message
    SessionItem:
      type: object
      description: 单条智能体会话记录。
      properties:
        session_id:
          type: string
          description: 会话标识。
        parent_session_id:
          type: string
          description: 子智能体（子）会话的父会话 ID；否则为空。
        session_name:
          type: string
          description: 会话标题；未命名会话可能为空。
        app_name:
          type: string
          description: 拥有该会话的智能体应用。
        entry_kind:
          type: string
          description: 创建该会话的入口来源。
          enum:
            - web
            - im
            - api
            - automation
            - subagent
        person_id:
          type: string
          description: 创建者人员 ID。
        team_id:
          type: integer
          format: int64
          description: 所属团队 ID；0 表示未绑定团队。创建后不可变更。
        team_name:
          type: string
          description: 解析出的团队名称；未绑定或团队已删除时为空。
        is_mine:
          type: boolean
          description: 当该会话由调用者创建时为 true。
        can_view:
          type: boolean
          description: 调用者可查看此会话时为 true。
        can_continue:
          type: boolean
          description: 调用者可在此会话中继续发起新轮次时为 true。
        can_manage:
          type: boolean
          description: 当调用者可重命名/归档/删除该会话时为 true；个人会话仅创建者可管理，团队会话允许创建者、账户管理员或团队成员管理。
        can_fork:
          type: boolean
          description: 调用者可从此会话创建分支时为 true。
        access_source:
          type: string
          description: 调用者获得该会话访问权限的方式；未解析到访问来源时省略。
          enum:
            - owner
            - team_member
            - manager
            - share_link
        share_enabled:
          type: boolean
          description: 会话的分享链接处于启用状态时为 true。
        share_version:
          type: integer
          format: int64
          description: 分享链接的版本号；撤销分享时会递增。
        shared_at:
          type: integer
          format: int64
          description: 最近一次启用分享的时间，Unix 毫秒时间戳；从未分享时为 0。
        shared_by:
          type: integer
          format: int64
          description: 最近一次启用分享的人员 ID；从未分享时为 0。
        status:
          type: string
          description: 生命周期状态。
          enum:
            - enabled
            - deleted
        incognito:
          type: boolean
          description: 无痕（不持久化记忆）会话时为 true。
        created_at:
          type: integer
          format: int64
          description: 会话创建时间，Unix 毫秒时间戳。
        updated_at:
          type: integer
          format: int64
          description: 会话最近更新时间，Unix 毫秒时间戳。
        template_staging_round_id:
          type: string
          description: 当前 save→validate 轮次 ID（仅 template-assistant）；否则为空。
        state:
          type: object
          additionalProperties: true
          description: 原始会话状态包（会话级键）。为空时省略。
        bound_environment:
          $ref: '#/components/schemas/EnvironmentBinding'
        context_resolved:
          $ref: '#/components/schemas/ContextResolvedItem'
        token_usage:
          $ref: '#/components/schemas/SessionTokenUsage'
        current_context_tokens:
          type: integer
          format: int64
          description: 截至最近一轮的 LLM 上下文窗口的 token 数。0 表示尚无已完成的轮次。
        context_window:
          type: integer
          format: int64
          description: 所绑定模型的最大上下文 token 数。0 表示未知。
        archived_at:
          type: integer
          format: int64
          description: 归档时间，Unix 毫秒时间戳；0 表示未归档。
        pinned_at:
          type: integer
          format: int64
          description: 调用者的个人置顶时间，Unix 毫秒时间戳；0 表示未置顶。
        last_event_at:
          type: integer
          format: int64
          description: 最近一条助手侧事件的时间，Unix 毫秒时间戳。
        is_running:
          type: boolean
          description: 当该会话当前有正在进行的智能体轮次时为 true。
        has_unread:
          type: boolean
          description: 当存在调用者尚未查看的助手输出时为 true。
        current_turn_started_at:
          type: integer
          format: int64
          description: 本轮（当前或最近一轮）开始时间，Unix 毫秒时间戳；尚未开始任何轮次时为 0。
        current_turn_active_ms:
          type: integer
          format: int64
          description: 本轮（当前或最近一轮）的实际工作时长（毫秒），不含等待 ask_user 的时间；每次新轮次开始时重置为 0。
        current_turn_wait_ms:
          type: integer
          format: int64
          description: 当前轮次累计的 ask_user 人工等待时长（毫秒）；每次新轮次开始时重置为 0。
        current_turn_tokens:
          type: integer
          format: int64
          description: >-
            当前进行中轮次的 token 总数（输入+输出+推理），涵盖父会话及其所有子智能体；仅由 session/get
            在会话运行时计算，session/list 响应及空闲时恒为 0。
      required:
        - session_id
        - session_name
        - app_name
        - person_id
        - team_id
        - is_mine
        - can_view
        - can_continue
        - can_manage
        - can_fork
        - share_enabled
        - share_version
        - shared_at
        - shared_by
        - status
        - incognito
        - created_at
        - updated_at
        - current_context_tokens
        - context_window
        - archived_at
        - pinned_at
        - is_running
        - has_unread
        - current_turn_started_at
        - current_turn_active_ms
        - current_turn_wait_ms
        - current_turn_tokens
    ErrorResponse:
      type: object
      description: Response envelope for errors. `error` is required; `data` is absent.
      properties:
        request_id:
          type: string
          example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
        error:
          $ref: '#/components/schemas/DutyError'
      required:
        - request_id
        - error
    ErrorCode:
      type: string
      description: >-
        Flashduty error code enum. Every failed API response sets `error.code`
        to one of these values. The value is a stable wire string — not a
        localized message and not a numeric status. HTTP status is
        informational.
      enum:
        - OK
        - InvalidParameter
        - BadRequest
        - InvalidContentType
        - ResourceNotFound
        - NoLicense
        - ReferenceExist
        - Unauthorized
        - BalanceNotEnough
        - AccessDenied
        - RouteNotFound
        - MethodNotAllowed
        - UndonedOrderExist
        - RequestLocked
        - EntityTooLarge
        - RequestTooFrequently
        - RequestVerifyRequired
        - DangerousOperation
        - InternalError
        - ServiceUnavailable
    EnvironmentBinding:
      type: object
      description: 会话绑定的 runner 或云沙箱。首条消息前为 null。
      properties:
        kind:
          type: string
          description: 会话当前绑定的环境类型：`cloud`（托管沙箱）或 `byoc`（自建 runner）。
          enum:
            - cloud
            - byoc
        id:
          type: string
          description: 环境标识：`cloud` 绑定为云沙箱 ID，`byoc` 绑定为 runner/环境 ID。
        name:
          type: string
          description: 可读的环境名称；cloud 绑定使用默认允许列表时为空。
        status:
          type: string
          description: >-
            绑定的实时健康状态，按类型分命名空间：BYOC 使用 online/pending/offline/deleted；cloud 使用
            available/rebuilding/expired。
          enum:
            - online
            - pending
            - offline
            - deleted
            - available
            - rebuilding
            - expired
      required:
        - kind
        - id
    ContextResolvedItem:
      type: object
      description: 该会话三层知识包解析结果的快照。
      properties:
        account_pack_id:
          type: string
          description: 解析出的账户级知识包 ID。
        team_pack_id:
          type: string
          description: 解析出的团队级知识包 ID。
        incident_id:
          type: string
          description: 作战室来源时绑定的故障 ID。
        resolved_at_ms:
          type: integer
          format: int64
          description: 知识包解析时间，Unix 毫秒时间戳。
        versions:
          type: object
          additionalProperties:
            type: integer
          description: 各知识包解析版本映射。
      required:
        - resolved_at_ms
    SessionTokenUsage:
      type: object
      description: 跨所有轮次的会话级 token 累计汇总。账户计费的权威来源。
      properties:
        input_tokens:
          type: integer
          format: int64
          description: 提示（输入）token 总数，含缓存部分。
        cached_tokens:
          type: integer
          format: int64
          description: input_tokens 中由提示缓存命中的部分。
        output_tokens:
          type: integer
          format: int64
          description: 生成（输出）token 总数。
        reasoning_tokens:
          type: integer
          format: int64
          description: 推理/思考 token 总数。
      required:
        - input_tokens
        - cached_tokens
        - output_tokens
        - reasoning_tokens
  responses:
    BadRequest:
      description: Invalid request — usually a missing or malformed parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingParameter:
              summary: Missing required parameter
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: InvalidParameter
                  message: The specified parameter skill_id is not valid.
    Unauthorized:
      description: Missing or invalid app_key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingAppKey:
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: Unauthorized
                  message: You are unauthorized.
    Forbidden:
      description: The app_key is valid but lacks permission for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            accessDenied:
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: AccessDenied
                  message: Access Denied.
    TooManyRequests:
      description: Rate limit hit. Either the global API limit or a per-account limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimited:
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: RequestTooFrequently
                  message: Request too frequently.
    ServerError:
      description: Unexpected server-side error. Include the request_id when reporting.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal:
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: InternalError
                  message: >-
                    We encountered an internal error, and it has been reported.
                    Please try again later.
  securitySchemes:
    AppKeyAuth:
      type: apiKey
      in: query
      name: app_key
      description: >-
        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.

````