FullStory Segments API

openapi: 3.2.0
info:
  title: FullStory Export Segments API
  description: The FullStory Segments Export API provides an asynchronous workflow for downloading captured event data from FullStory.
  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: Segments
  description: Retrieve segment metadata including name, creator, and creation time.
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'
components:
  schemas:
    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.
    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
    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.
  parameters:
    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
    SegmentIdPath:
      name: segmentId
      in: path
      required: true
      description: The unique identifier for the segment
      schema:
        type: string
    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
  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/