openapi: 3.1.0
info:
  title: FullStory Segments Export Batch Import Exports 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: Exports
  description: Create and manage asynchronous export jobs for segment data, including both individual and event exports.
paths:
  /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'
components:
  schemas:
    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
    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
    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
  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/