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

# List roleplay sessions

> Returns a paginated list of roleplay sessions in the workspace with inline user and scenario data.

Sessions represent individual practice attempts on AI roleplay scenarios. Each session
includes the participant's score, rank, duration, and metadata. Use filters to narrow
results by user, scenario, skill, program, group, or date range.

Note: Sessions may include users who are no longer active workspace members (e.g., users
who have been removed). These users will not appear in GET /workspace/members but their
historical session data is preserved.

Results are ordered by creation date (newest first) by default.




## OpenAPI

````yaml /api-reference/openapi.yaml get /sessions
openapi: 3.0.3
info:
  title: Exec API
  version: '1.0'
  description: >
    REST API for programmatic access to your Exec workspace.


    Use the Exec API to read workspace data, list members, retrieve group
    information,

    and create interactive scenario creation sessions.


    ## Authentication

    All requests require a valid API key passed in the Authorization header:

    ```

    Authorization: Bearer exec_live_...

    ```


    Create API keys in your workspace settings under **Settings > API**.
servers:
  - url: https://api.exec.com/rest/v1
    description: Production
security:
  - bearerAuth: []
paths:
  /sessions:
    get:
      tags:
        - Sessions
      summary: List roleplay sessions
      description: >
        Returns a paginated list of roleplay sessions in the workspace with
        inline user and scenario data.


        Sessions represent individual practice attempts on AI roleplay
        scenarios. Each session

        includes the participant's score, rank, duration, and metadata. Use
        filters to narrow

        results by user, scenario, skill, program, group, or date range.


        Note: Sessions may include users who are no longer active workspace
        members (e.g., users

        who have been removed). These users will not appear in GET
        /workspace/members but their

        historical session data is preserved.


        Results are ordered by creation date (newest first) by default.
      operationId: listSessions
      parameters:
        - name: user_ids
          in: query
          description: >-
            Comma-separated user IDs to filter by. When combined with
            user_emails, results are unioned (all matching users from either
            list are included).
          schema:
            type: string
            example: u1a2b3c4d5e6,u7v8w9x0y1z2
        - name: user_emails
          in: query
          description: >-
            Comma-separated user email addresses to filter by. When combined
            with user_ids, results are unioned (all matching users from either
            list are included).
          schema:
            type: string
            example: jane@acme.com,bob@acme.com
        - name: scenario_ids
          in: query
          description: Comma-separated scenario IDs to filter by
          schema:
            type: string
        - name: collection_ids
          in: query
          description: Comma-separated collection IDs to filter by
          schema:
            type: string
        - name: skill_ids
          in: query
          description: Comma-separated skill IDs to filter by
          schema:
            type: string
        - name: program_ids
          in: query
          description: Comma-separated program IDs to filter by
          schema:
            type: string
        - name: group_ids
          in: query
          description: Comma-separated workspace group IDs to filter by
          schema:
            type: string
        - name: rank
          in: query
          description: Filter by one or more performance ranks
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - gold
                - silver
                - bronze
                - unranked
            example:
              - gold
              - silver
        - name: start_date
          in: query
          description: >-
            ISO 8601 datetime — only include sessions created on or after this
            date
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          description: >-
            ISO 8601 datetime — only include sessions created on or before this
            date
          schema:
            type: string
            format: date-time
        - name: exclude_system_users
          in: query
          description: >-
            Exclude sessions from system users (emails ending in @exec.com).
            Default false.
          schema:
            type: boolean
            default: false
        - name: sorting
          in: query
          description: Sort field. Prefix with `-` for descending order.
          schema:
            type: string
            default: '-created_at'
            enum:
              - created_at
              - '-created_at'
              - score
              - '-score'
              - duration
              - '-duration'
        - name: page
          in: query
          description: Page number (1-indexed)
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: page_size
          in: query
          description: Number of results per page (max 100)
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Paginated list of roleplay sessions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SessionListItem'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                  - id: abc123def456
                    user:
                      id: u1a2b3c4d5e6
                      email: jane@acme.com
                      first_name: Jane
                      last_name: Smith
                    scenario:
                      id: s1a2b3c4d5e6
                      name: Procurement Discovery
                      slug: procurement-discovery
                    score: 82.5
                    rank: gold
                    duration_seconds: 347
                    is_valid_attempt: true
                    created_at: '2026-03-15T14:30:00Z'
                pagination:
                  page: 1
                  page_size: 50
                  total_count: 128
                  total_pages: 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    SessionListItem:
      type: object
      description: A roleplay session summary for list responses.
      properties:
        id:
          type: string
          description: Unique session identifier
        user:
          $ref: '#/components/schemas/User'
          description: The user who participated in this session
        scenario:
          $ref: '#/components/schemas/ScenarioRef'
          description: The scenario that was practiced
        score:
          type: number
          nullable: true
          description: Session score (0-100 scale)
        rank:
          type: string
          nullable: true
          enum:
            - gold
            - silver
            - bronze
            - unranked
          description: Performance rank based on score
        duration_seconds:
          type: number
          nullable: true
          description: Session duration in seconds
        is_valid_attempt:
          type: boolean
          description: >-
            Whether this session counts as a valid graded attempt. A session is
            valid when it was completed (not abandoned), received AI grading,
            and has a score. Use valid attempts for analytics; non-valid
            sessions may be incomplete or ungraded.
        created_at:
          type: string
          format: date-time
          description: When the session was created
    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
        total_count:
          type: integer
          description: Total number of items
        total_pages:
          type: integer
          description: Total number of pages
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique user identifier
        email:
          type: string
          format: email
          description: User's email address
        first_name:
          type: string
          description: User's first name
        last_name:
          type: string
          description: User's last name
    ScenarioRef:
      type: object
      description: A compact scenario reference for embedding in other responses.
      properties:
        id:
          type: string
          description: Unique scenario identifier
        name:
          type: string
          description: Scenario name
        slug:
          type: string
          description: URL-friendly scenario identifier
    ValidationErrorDetail:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error category (e.g., "invalid_request")
            code:
              type: string
              description: Specific error code (e.g., "user_not_found")
            message:
              type: string
              description: Human-readable error message
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorDetail'
          example:
            error:
              type: invalid_request
              code: invalid_pagination
              message: Invalid pagination parameters
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorDetail'
          example:
            error:
              type: authentication_error
              code: invalid_api_key
              message: Invalid or inactive API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API key created in Settings > API.

        Format: `exec_live_` followed by 40 alphanumeric characters.

````