FullStory Sessions API

openapi: 3.2.0
info:
  title: FullStory Segments Export Batch Import Sessions API
  description: 'The FullStory Segments Export API provides an asynchronous workflow for downloading captured event data from FullStory. Developers can initiate export jobs to aggregate segment data, query for the status of running jobs, and retrieve download URLs for completed exports. Two types of segment data are available for export: individuals matching a segment and events performed by those individuals. This API is useful for integrating FullStory behavioral data into external analytics pipelines and data warehouses.'
  version: '1.0'
  contact:
    name: FullStory Support
    url: https://help.fullstory.com/
  termsOfService: https://www.fullstory.com/legal/terms-and-conditions/
servers:
- url: https://api.fullstory.com
  description: FullStory Production API Server
security:
- basicAuth: []
tags:
- name: Sessions
  description: Retrieve session replay URLs for users and access recorded session data. Sessions are scoped to a single FullStory account and replay URLs require authenticated FullStory access.
paths:
  /sessions/v2:
    get:
      operationId: listSessions
      summary: List sessions for a user
      description: Returns a list of session replay URLs for a given user, queried by email address and/or uid. If both uid and email are provided, the API queries on them separately and returns a union of the records. It is recommended to use either uid or email, but not both. By default, the last 20 sessions are returned.
      tags:
      - Sessions
      parameters:
      - $ref: '#/components/parameters/EmailQuery'
      - $ref: '#/components/parameters/UidQuery'
      - $ref: '#/components/parameters/LimitQuery'
      responses:
        '200':
          description: List of session URLs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionList'
        '400':
          description: Invalid input - at least one of email or uid is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    LimitQuery:
      name: limit
      in: query
      required: false
      description: Maximum number of sessions to return. Defaults to 20.
      schema:
        type: integer
        default: 20
        minimum: 1
    EmailQuery:
      name: email
      in: query
      required: false
      description: Email address of the user whose sessions to retrieve
      schema:
        type: string
        format: email
    UidQuery:
      name: uid
      in: query
      required: false
      description: External user identifier of the user whose sessions to retrieve
      schema:
        type: string
  schemas:
    Session:
      type: object
      description: A session replay reference with URL and metadata
      properties:
        sessionId:
          type: string
          description: Unique identifier for the session
        url:
          type: string
          format: uri
          description: URL to view the session replay in the FullStory application. Only accessible by browsers logged into the appropriate FullStory account.
        created:
          type: string
          format: date-time
          description: Timestamp when the session was recorded
    Error:
      type: object
      description: Standard error response from the FullStory API
      properties:
        code:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Human-readable error message
    SessionList:
      type: object
      description: List of session replay URLs for a user
      properties:
        sessions:
          type: array
          description: Array of session objects with replay URLs
          items:
            $ref: '#/components/schemas/Session'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: API key passed in the Authorization header using Basic authentication. Admin or Architect level keys are required.
externalDocs:
  description: FullStory Segments Export API Documentation
  url: https://developer.fullstory.com/server/v1/segments/create-segment-export/