> ## Documentation Index
> Fetch the complete documentation index at: https://docs.membrane.agency/llms.txt
> Use this file to discover all available pages before exploring further.

# List agent sessions



## OpenAPI

````yaml /api-reference/membrane-api.json get /agent/sessions
openapi: 3.0.0
info:
  title: Membrane API
  description: API documentation for Membrane Engine
  version: '1.0'
  contact: {}
servers:
  - url: https://api.getmembrane.com
security:
  - bearer: []
tags: []
paths:
  /agent/sessions:
    get:
      tags:
        - Sessions
      summary: List agent sessions
      operationId: listAgentSessions
      parameters:
        - name: limit
          required: false
          in: query
          description: Maximum number of items to return (1-1000)
          schema:
            minimum: 1
            maximum: 1000
            type: integer
        - name: cursor
          required: false
          in: query
          description: Pagination cursor from a previous response
          schema:
            type: string
        - name: workspaceElementType
          required: false
          in: query
          schema:
            type: string
            enum:
              - tenant
              - app
              - connector
              - integration
              - action
              - connection
              - data-table
              - data-table-record
              - data-sync
              - data-sync-run
              - external-event-subscription
              - external-event-log-record
              - external-event-pull
              - external-event-type
              - action-run-log-record
              - external-api-log-record
              - incoming-webhook-log-record
              - connected-product
              - external-agent
              - job
              - deliverable
              - deliverable-type
              - routine
              - task
              - canvas
              - file
              - knowledge-article
              - knowledge-sync
              - knowledge-sync-pull
        - name: workspaceElementId
          required: false
          in: query
          schema:
            type: string
        - name: relatedElementType
          required: false
          in: query
          description: >-
            Return sessions started from or associated with this element. Pair
            with relatedElementId.
          schema:
            type: string
            enum:
              - tenant
              - app
              - connector
              - integration
              - action
              - connection
              - data-table
              - data-table-record
              - data-sync
              - data-sync-run
              - external-event-subscription
              - external-event-log-record
              - external-event-pull
              - external-event-type
              - action-run-log-record
              - external-api-log-record
              - incoming-webhook-log-record
              - connected-product
              - external-agent
              - job
              - deliverable
              - deliverable-type
              - routine
              - task
              - canvas
              - file
              - knowledge-article
              - knowledge-sync
              - knowledge-sync-pull
        - name: relatedElementId
          required: false
          in: query
          description: >-
            Return sessions started from or associated with this element. Pair
            with relatedElementType.
          schema:
            type: string
        - name: agentHarnessId
          required: false
          in: query
          schema:
            type: string
        - name: preset
          required: false
          in: query
          description: Filter sessions by the preset (situation) the agent ran in.
          schema:
            type: string
            enum:
              - general
              - canvas
              - context
              - connection-build
              - action-build
              - task
              - work
              - universe
        - name: startDatetime
          required: false
          in: query
          schema:
            type: string
            format: date-time
            pattern: >-
              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        - name: endDatetime
          required: false
          in: query
          schema:
            type: string
            format: date-time
            pattern: >-
              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - queued
              - starting
              - running
              - completed
              - failed
              - cancelled
        - name: isExternal
          required: false
          in: query
          schema:
            type: boolean
        - name: parentSessionId
          required: false
          in: query
          description: >-
            When omitted, the listing returns top-level sessions only. Pass a
            session id to fetch its direct children.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSessionsPaginatedResponseDto'
components:
  schemas:
    AgentSessionsPaginatedResponseDto:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              userId:
                type: string
              tenantId:
                type: string
              ownerName:
                type: string
                nullable: true
              id:
                type: string
              workspaceId:
                type: string
              orgWorkspaceId:
                type: string
              workspaceElementType:
                type: string
                enum:
                  - tenant
                  - app
                  - connector
                  - integration
                  - action
                  - connection
                  - data-table
                  - data-table-record
                  - data-sync
                  - data-sync-run
                  - external-event-subscription
                  - external-event-log-record
                  - external-event-pull
                  - external-event-type
                  - action-run-log-record
                  - external-api-log-record
                  - incoming-webhook-log-record
                  - connected-product
                  - external-agent
                  - job
                  - routine
                  - task
                  - canvas
                  - knowledge-article
                  - knowledge-sync
                  - knowledge-sync-pull
              workspaceElementId:
                type: string
              type:
                type: string
              status:
                type: string
                enum:
                  - queued
                  - starting
                  - running
                  - completed
                  - failed
                  - cancelled
              prompt:
                type: string
              error:
                $ref: >-
                  #/components/schemas/AgentSessionsPaginatedResponseDto__schema0
              lastActivityAt:
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                description: >-
                  Last meaningful session progress timestamp used for inactivity
                  timeout checks.
              archivedAt:
                description: >-
                  When set, the session is archived (soft-deleted) and hidden
                  from lists.
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
              title:
                type: string
              summary:
                type: string
              cost:
                type: number
              state:
                default: busy
                type: string
                enum:
                  - busy
                  - idle
              hasWorker:
                type: boolean
              isExternal:
                type: boolean
              preset:
                description: >-
                  Which situation the one membrane agent runs in — selects the
                  skills + context it loads.
                type: string
                enum:
                  - general
                  - canvas
                  - context
                  - connection-build
                  - action-build
                  - task
                  - work
                  - universe
              launchContext:
                description: >-
                  Where the session was launched from — the resolved surface /
                  route / element envelope shared by the console UI and the
                  agent.
                type: object
                properties:
                  surface:
                    description: >-
                      The UI surface the session renders in (console chat,
                      context rail, connect popup, …).
                    type: string
                    enum:
                      - console-chat
                      - context-rail
                      - table-chat
                      - connect-popup
                      - mcp-embedded
                      - cli
                      - desktop
                      - background
                  route:
                    description: >-
                      The app route the user was on when they launched the
                      session, e.g. "/w/0?element=%2Fconnections%2F123".
                    type: string
                    maxLength: 2000
                  element:
                    description: >-
                      The workspace element the launch is anchored to — the
                      element the user is looking at, or an element type when
                      launched from a list.
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - tenant
                          - app
                          - connector
                          - integration
                          - action
                          - connection
                          - data-table
                          - data-table-record
                          - data-sync
                          - data-sync-run
                          - external-event-subscription
                          - external-event-log-record
                          - external-event-pull
                          - external-event-type
                          - action-run-log-record
                          - external-api-log-record
                          - incoming-webhook-log-record
                          - connected-product
                          - external-agent
                          - job
                          - routine
                          - task
                          - canvas
                          - knowledge-article
                          - knowledge-sync
                          - knowledge-sync-pull
                      id:
                        type: string
                        minLength: 1
                    required:
                      - type
              agentHarnessId:
                type: string
              agentHarnessSnapshotId:
                type: string
              output:
                type: object
                additionalProperties:
                  type: object
              outputAttachments:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    data:
                      type: object
                  required:
                    - title
                    - data
              parentSessionId:
                type: string
              createdAt:
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
              updatedAt:
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            required:
              - id
              - workspaceId
              - type
              - status
              - prompt
              - lastActivityAt
              - hasWorker
              - createdAt
              - updatedAt
        cursor:
          type: string
      required:
        - items
    AgentSessionsPaginatedResponseDto__schema0:
      type: object
      properties:
        type:
          type: string
          enum:
            - bad_request
            - connection
            - configuration
            - dependency_error
            - flow_run
            - flow_instance_setup
            - concurrency
            - internal
            - action_run
            - action_instance_setup
            - unit_run
            - custom_code
            - insufficient_credit
            - openrouter_not_configured
        key:
          type: string
        message:
          type: string
        data:
          type: object
        stack:
          type: object
        causedByError:
          $ref: '#/components/schemas/AgentSessionsPaginatedResponseDto__schema0'
        logs:
          type: array
          items:
            type: object
      required:
        - message
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````