openapi: 3.1.0
info:
  title: FullStory Segments Export Batch Import Operations 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: Operations
  description: Query the status of long-running asynchronous operations such as segment exports, and retrieve results when complete.
paths:
  /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:
  parameters:
    OperationIdPath:
      name: operationId
      in: path
      required: true
      description: The unique identifier for the operation
      schema:
        type: string
  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
  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/