openapi: 3.1.0
info:
  title: FullStory Segments Export 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/
externalDocs:
  description: FullStory Segments Export API Documentation
  url: https://developer.fullstory.com/server/v1/segments/create-segment-export/
servers:
  - url: https://api.fullstory.com
    description: FullStory Production API Server
tags:
  - name: Exports
    description: >-
      Create and manage asynchronous export jobs for segment data, including
      both individual and event exports.
  - name: Operations
    description: >-
      Query the status of long-running asynchronous operations such as
      segment exports, and retrieve results when complete.
  - name: Segments
    description: >-
      Retrieve segment metadata including name, creator, and creation time.
security:
  - basicAuth: []
paths:
  /segments/v1:
    get:
      operationId: listSegments
      summary: List segments
      description: >-
        Returns a paginated list of segments for the organization. You can
        optionally limit the number of segments returned, with a default of
        20 and a maximum of 100 per page. Use the pagination token to
        retrieve additional pages of results.
      tags:
        - Segments
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/PaginationToken'
      responses:
        '200':
          description: List of segments retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentList'
        '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'
  /segments/v1/{segmentId}:
    get:
      operationId: getSegment
      summary: Get a segment
      description: >-
        Returns segment information for the provided segment ID, including
        the segment name, creator email, and creation timestamp.
      tags:
        - Segments
      parameters:
        - $ref: '#/components/parameters/SegmentIdPath'
      responses:
        '200':
          description: Segment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Segment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /segments/v1/exports:
    post:
      operationId: createSegmentExport
      summary: Create a segment export
      description: >-
        Schedules an asynchronous export based on the provided segment. The
        progress and results of the export can be fetched from the operations
        API. Two export types are available: individuals (information about
        users matching the segment) and events (events performed by matching
        users).
      tags:
        - Exports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExportRequest'
      responses:
        '200':
          description: Export job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        '400':
          description: Invalid input provided
          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'
  /operations/v1/{operationId}:
    get:
      operationId: getOperationStatus
      summary: Get operation status
      description: >-
        Returns the status of a particular operation given the operation ID.
        When an operation is running, the response includes state, estimated
        completion percentage, and timestamps. When complete, results include
        download URLs for exported data.
      tags:
        - Operations
      parameters:
        - $ref: '#/components/parameters/OperationIdPath'
      responses:
        '200':
          description: Operation status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Operation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        API key passed in the Authorization header using Basic authentication.
        Admin or Architect level keys are required.
  parameters:
    SegmentIdPath:
      name: segmentId
      in: path
      required: true
      description: >-
        The unique identifier for the segment
      schema:
        type: string
    OperationIdPath:
      name: operationId
      in: path
      required: true
      description: >-
        The unique identifier for the operation
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: >-
        Maximum number of segments to return per page. Default is 20,
        maximum is 100.
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    PaginationToken:
      name: pagination_token
      in: query
      required: false
      description: >-
        Token for retrieving the next page of results. Do not change other
        list parameters between consecutive paginated requests.
      schema:
        type: string
  schemas:
    Segment:
      type: object
      description: >-
        A FullStory segment representing a saved group of users matching
        specific behavioral criteria
      properties:
        id:
          type: string
          description: >-
            Unique identifier for the segment
        name:
          type: string
          description: >-
            Display name of the segment
        creator:
          type: string
          format: email
          description: >-
            Email address of the FullStory user who created the segment
        created:
          type: string
          format: date-time
          description: >-
            UTC RFC 3339 timestamp for when the segment was created. Not
            present for built-in segments.
    SegmentList:
      type: object
      description: >-
        Paginated list of segments
      properties:
        segments:
          type: array
          description: >-
            Array of segment objects
          items:
            $ref: '#/components/schemas/Segment'
        pagination_token:
          type: string
          description: >-
            Token to retrieve the next page of results. Absent when no
            more pages are available.
    CreateExportRequest:
      type: object
      required:
        - segmentId
        - type
      description: >-
        Request body for creating a segment export job
      properties:
        segmentId:
          type: string
          description: >-
            The ID of the segment to export
        type:
          type: string
          description: >-
            The type of data to export. Use individuals for user data or
            events for behavioral event data.
          enum:
            - individuals
            - events
        format:
          type: string
          description: >-
            The output format for the export
          enum:
            - json
            - csv
        timeRange:
          type: object
          description: >-
            Optional time range to filter the exported data
          properties:
            start:
              type: string
              format: date-time
              description: >-
                Start of the time range in RFC 3339 format
            end:
              type: string
              format: date-time
              description: >-
                End of the time range in RFC 3339 format
        segmentTimeRange:
          type: object
          description: >-
            Optional time range for segment membership evaluation
          properties:
            start:
              type: string
              format: date-time
              description: >-
                Start of the segment evaluation time range
            end:
              type: string
              format: date-time
              description: >-
                End of the segment evaluation time range
    Operation:
      type: object
      description: >-
        Represents an asynchronous operation such as a segment export
      properties:
        id:
          type: string
          description: >-
            Unique identifier for the operation
        type:
          type: string
          description: >-
            The type of operation
        state:
          type: string
          description: >-
            Current state of the operation
          enum:
            - PENDING
            - RUNNING
            - COMPLETED
            - FAILED
        errorDetails:
          type: string
          description: >-
            Error details if the operation failed
        createdAt:
          type: string
          format: date-time
          description: >-
            Timestamp when the operation was created
        finishedAt:
          type: string
          format: date-time
          description: >-
            Timestamp when the operation finished. Null while running.
        estimatePctComplete:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: >-
            Estimated percentage of completion for the operation
        results:
          type: object
          description: >-
            Results of the operation when completed, including download URLs
          properties:
            downloadUrl:
              type: string
              format: uri
              description: >-
                URL for downloading the exported data
    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