Convert Visitor Insights API

openapi: 3.2.0
info:
  title: Convert Visitor Insights API
  description: Move your app forward with the Convert API.
  version: 2.0.0
servers:
- url: https://api.convert.com/api/v2
  description: Live API server
- url: https://apidev.convert.com/api/v2
  description: DEV API server
- url: http://apidev.convert.com:5000/api/v2
  description: DEV mocked API server
tags:
- name: Visitor Insights
  description: Visitor Insights for the project
paths:
  /accounts/{account_id}/projects/{project_id}/sessions:
    post:
      operationId: getSessionsList
      summary: List recorded visitor sessions for a project
      tags:
      - Visitor Insights
      description: 'Retrieves a list of recorded visitor sessions for a specific project.

        This endpoint is typically used for integrations that require access to raw session data.

        Note: This is different from Convert Signals. For frustration and usability insights, see the Signal Sessions endpoint.'
      parameters:
      - name: account_id
        in: path
        required: true
        description: ID of the account that owns the retrieved/saved data
        schema:
          type: integer
      - name: project_id
        in: path
        required: true
        description: ID of the project to be retrieved
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/GetSessionsRequest'
      responses:
        '200':
          $ref: '#/components/responses/SessionsListResponse'
  /accounts/{account_id}/projects/{project_id}/signal_sessions:
    post:
      operationId: getSignalSessionsList
      summary: List Convert Signals™ (visitor frustration sessions)
      description: 'Retrieves a list of Convert Signals™ sessions for a project.

        Convert Signals™ "is a special anonymous and privacy oriented session recording feature...It shows only really clear frustrations, errors and usability signals of real users".

        Use this to identify sessions where visitors experienced issues like rage clicks, dead clicks, or scroll stalls.

        Supports filtering by date, experience, variation, location, country, device, browser, and more.'
      tags:
      - Visitor Insights
      parameters:
      - name: account_id
        in: path
        required: true
        description: ID of the account that owns the retrieved/saved data
        schema:
          type: integer
      - name: project_id
        in: path
        required: true
        description: ID of the project to be retrieved
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/GetSignalSessionsRequest'
      responses:
        '200':
          $ref: '#/components/responses/SignalSessionsListResponse'
  /accounts/{account_id}/projects/{project_id}/signal_sessions/{signal_session_id}:
    delete:
      operationId: deleteSignalSession
      summary: Delete a specific Convert Signals™ session
      description: Permanently removes a recorded Convert Signals™ session, identified by its `signal_session_id`.
      tags:
      - Visitor Insights
      parameters:
      - name: account_id
        in: path
        required: true
        description: ID of the account that owns the retrieved/saved data
        schema:
          type: integer
      - name: project_id
        in: path
        required: true
        description: ID of the project to be retrieved
        schema:
          type: integer
      - name: signal_session_id
        in: path
        required: true
        description: ID of the signal session to be deleted
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    SignalSessionsList:
      type: array
      description: A list of Convert Signals™ session objects. Each object represents a recorded session where user frustration or usability issues were detected.
      items:
        $ref: '#/components/schemas/SignalSession'
    ErrorData:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        fields:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
    Extra:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
    SuccessData:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Pagination:
      type: object
      properties:
        current_page:
          description: The current page number being displayed from the paginated set.
          type: integer
          minimum: 1
        items_count:
          description: The total number of items available across all pages for the current filter criteria.
          type: integer
          minimum: 0
        items_per_page:
          description: The number of items included in the current page of results (matches `results_per_page` from the request).
          type: integer
          minimum: 0
        pages_count:
          description: The total number of pages available for the current filter criteria and `results_per_page` setting.
          type: integer
          minimum: 0
    SignalSessionsListResponseData:
      type: object
      description: Response containing a list of Convert Signals™ sessions (highlighting user frustrations), along with pagination and filtering metadata.
      properties:
        data:
          $ref: '#/components/schemas/SignalSessionsList'
        extra:
          allOf:
          - type: object
            properties:
              tk:
                type: string
                nullable: true
                description: Extra property
          - $ref: '#/components/schemas/Extra'
    ResultsPerPage:
      type: object
      properties:
        results_per_page:
          type: integer
          nullable: true
          minimum: 0
          maximum: 50
          default: 30
          description: 'Specifies the maximum number of items to return in a single page of results.

            Used for pagination. Default is 30, maximum is 50.

            '
    GetSessionsListRequestData:
      allOf:
      - $ref: '#/components/schemas/SessionsListFilteringOptions'
    OnlyCount:
      type: object
      properties:
        onlyCount:
          type: boolean
          description: 'If set to `true` in a list request, the response will only contain the total count of matching items (`extra.pagination.items_count`)

            and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

            '
    GetSignalSessionsListRequestData:
      $ref: '#/components/schemas/SignalSessionsListFilteringOptions'
    PageNumber:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          description: 'The page number for paginated results. For example, if `results_per_page` is 30, `page: 2` will retrieve items 31-60.

            Defaults to 1 if not specified.

            '
    UTC_Offset:
      type: integer
      description: 'The time offset from Coordinated Universal Time (UTC) in seconds.

        For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200.

        Used for interpreting or displaying date/time information according to a specific timezone.

        '
      default: 0
      minimum: -43200
      maximum: 50400
    SignalSession:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for this Convert Signals™ session recording.
          readOnly: true
        duration:
          type: integer
          description: The total duration of the recorded session in seconds.
        visited_pages:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              duration:
                type: integer
              timestamp:
                type: integer
                format: int64
        visited_pages_count:
          type: integer
          description: The total number of unique pages visited during this session.
        entry_page:
          type: string
          description: The URL of the first page visited in this session (landing page for the session).
        exit_page:
          type: string
          description: The URL of the last page visited before the session ended or the visitor exited.
        session_start_time:
          type: integer
          format: int64
          description: Unix timestamp (UTC) indicating when this session recording started.
        device:
          type: string
          description: The type of device used by the visitor during this session (e.g., "Desktop", "Mobile", "Tablet").
        browser:
          type: string
          description: The web browser used by the visitor (e.g., "Chrome", "Firefox", "Safari").
        country_code:
          type: string
          description: The two-letter ISO country code of the visitor's location, based on IP geolocation.
        watched:
          type: boolean
          description: True if this session recording has been watched by a user in the Convert UI.
    SessionsListFilteringOptions:
      allOf:
      - $ref: '#/components/schemas/TimeRange'
      - type: object
        properties:
          tags:
            type: object
            nullable: true
            additionalProperties:
              type: string
            description: 'The tags object containing key-value pairs where each key is the tag name and the value is a string representing the tag''s value.

              '
            example:
              property1: value1
              property2: value2
    SessionsListResponseData:
      type: object
      description: Response containing a list of recorded raw visitor sessions for a project, along with pagination details. (This endpoint seems to be for general session data, distinct from Convert Signals).
      properties:
        data:
          $ref: '#/components/schemas/SessionsList'
        extra:
          allOf:
          - type: object
            properties:
              tk:
                type: string
                nullable: true
                description: Extra property
    SignalSessionsListFilteringOptions:
      allOf:
      - $ref: '#/components/schemas/TimeRange'
      - $ref: '#/components/schemas/PageNumber'
      - $ref: '#/components/schemas/ResultsPerPage'
      - $ref: '#/components/schemas/OnlyCount'
      - type: object
        properties:
          experience:
            type: object
            additionalProperties: false
            nullable: true
            properties:
              id:
                type: integer
                description: The ID of the experience to filter by
              variation_id:
                type: integer
                description: The ID of the variation to filter by
          location_id:
            type: integer
            nullable: true
            description: The ID of the location to filter by
          starred:
            type: string
            nullable: true
          watched:
            type: string
            nullable: true
          country:
            type: object
            nullable: true
            additionalProperties: false
            properties:
              is:
                type: array
                items:
                  type: string
              isNot:
                type: array
                items:
                  type: string
          os:
            type: object
            additionalProperties: false
            nullable: true
            properties:
              is:
                type: array
                items:
                  type: string
              isNot:
                type: array
                items:
                  type: string
          browser:
            type: object
            nullable: true
            additionalProperties: false
            properties:
              is:
                type: array
                items:
                  type: string
              isNot:
                type: array
                items:
                  type: string
          devices:
            type: object
            nullable: true
            additionalProperties: false
            properties:
              is:
                type: array
                items:
                  type: string
              isNot:
                type: array
                items:
                  type: string
          containsPage:
            type: string
            nullable: true
          notContainsPage:
            type: string
            nullable: true
          duration:
            type: object
            nullable: true
            additionalProperties: false
            description: 'The duration of the signal session in seconds

              '
            properties:
              min:
                type: integer
              max:
                type: integer
          pageCount:
            type: object
            nullable: true
            additionalProperties: false
            properties:
              min:
                type: integer
              max:
                type: integer
          entryPage:
            type: string
            nullable: true
          exitPage:
            type: string
            nullable: true
          referrerURLs:
            type: array
            items:
              type: string
            nullable: true
          trafficChannels:
            type: array
            items:
              type: string
            nullable: true
          adCampaignLabels:
            type: array
            items:
              type: string
            nullable: true
          recordingId:
            type: string
            nullable: true
    Session:
      type: object
      properties:
        id:
          type: integer
          description: The unique numerical identifier for this raw session.
          readOnly: true
    SessionsList:
      type: array
      description: A list of raw session objects.
      items:
        $ref: '#/components/schemas/Session'
    TimeRange:
      type: object
      properties:
        start_time:
          type: number
          nullable: true
          description: Unix timestamp (seconds since epoch, UTC) marking the beginning of the time range. If null, implies from the beginning of data.
        end_time:
          type: number
          nullable: true
          description: Unix timestamp (seconds since epoch, UTC) marking the end of the time range. If null, implies up to the current time.
        utc_offset:
          $ref: '#/components/schemas/UTC_Offset'
  requestBodies:
    GetSignalSessionsRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetSignalSessionsListRequestData'
    GetSessionsRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetSessionsListRequestData'
  responses:
    SignalSessionsListResponse:
      description: A list of Convert Signals™ sessions, highlighting visitor interactions that indicate potential frustration or usability issues (e.g., rage clicks, dead clicks). Includes session duration, visited pages, location, and other metadata.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignalSessionsListResponseData'
    SessionsListResponse:
      description: A list of recorded raw visitor sessions for a project, typically used for deep-dive analytics or integrations requiring session-level data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SessionsListResponseData'
    SuccessResponse:
      description: 'A generic success response, typically used for operations that don''t return specific data (like deletions or some updates). The `code` is usually 200, and `message` confirms the successful action.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessData'
    ErrorResponse:
      description: 'Indicates an error occurred while processing the request. The `code` provides an HTTP status code, `message` offers a human-readable explanation or an array of validation errors, and `fields` (if present) specifies which input fields were problematic.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorData'
  securitySchemes:
    requestSigning:
      type: apiKey
      x-name-applicationId: Convert-Application-ID
      x-name-expire: Expire
      name: Authorization
      in: header
      description: 'See **[API Key Authentication](#tag/API-KEY-Authentication)** for more information.

        '
    secretKey:
      type: http
      scheme: bearer
      description: 'See **[API Key Authentication](#tag/API-KEY-Authentication)** for more information.

        '
    cookieAuthentication:
      type: apiKey
      in: cookie
      name: sid
      description: Cookie authentication is used against Convert's own IdentityProvider  or third party identity providers and is described more in the "[Cookie Authentication](#tag/Cookie-Authentication)" section
x-tagGroups:
- name: Client Authentication
  tags:
  - API KEY Authentication
  - Cookie Authentication
  - OAuth Authorization
- name: Common Parameters
  tags:
  - Optional Fields
  - Expandable Fields
- name: Requests
  tags:
  - User
  - Accounts
  - AI content
  - Collaborators
  - API Keys
  - Projects
  - SDK Keys
  - Experiences
  - Experience Variations
  - Experience Sections
  - Section Versions
  - Version Changes
  - Experiences Reports
  - Experiences Heatmaps
  - Goals
  - Hypotheses
  - Knowledge Bases
  - Observations
  - Locations
  - Audiences
  - Domains
  - Cdn Images
  - Files
  - Tags
  - Features
  - Visitor Insights
  - Visitors Data
  - Visitor Data Placeholders
  - OAuth