> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List ban safe health history

> Returns the newest Health evaluations since the requested date, up to the limit, ordered oldest to newest. Each point carries its estimator source and version, evidence coverage, reliability, and availability reason.

Requires `sessions:read`. Project tokens only access resources in their own project.



## OpenAPI

````yaml api-reference/features/operate.json GET /platform/bansafe/health/{session}/history
openapi: 3.0.3
info:
  title: Operate API methods
  version: 1.0.0
  description: Task-focused operate methods across supported Polymorfa connection types.
servers: []
security: []
paths:
  /platform/bansafe/health/{session}/history:
    get:
      tags:
        - Bansafe
      summary: List ban safe health history
      description: >-
        Returns the newest Health evaluations since the requested date, up to
        the limit, ordered oldest to newest. Each point carries its estimator
        source and version, evidence coverage, reliability, and availability
        reason.


        Requires `sessions:read`. Project tokens only access resources in their
        own project.
      operationId: managementListBanSafeHealthHistory
      parameters:
        - name: session
          in: path
          required: true
          schema:
            type: string
          description: Identifier of the connected Polymorfa session.
        - name: since
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: |-
            Specifies since for this query parameter.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `date-time` |
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 720
            default: 720
          description: |-
            Specifies limit for this query parameter.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `1` through `720` (inclusive) |
      responses:
        '200':
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Stable request correlation identifier.
            Polymorfa-Version:
              schema:
                type: string
              description: API version applied to this response.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/management__BanSafeHealthHistory'
                    description: Structured data carried by this object.
                required:
                  - data
        '400':
          $ref: '#/components/responses/management__BadRequest'
        '401':
          $ref: '#/components/responses/management__Unauthorized'
        '403':
          $ref: '#/components/responses/management__Forbidden'
        '404':
          $ref: '#/components/responses/management__NotFound'
      security:
        - management__ApiKeyAuth: []
      servers:
        - url: https://api.polymorfa.com
        - url: http://localhost:8080
          description: local dev
components:
  schemas:
    management__BanSafeHealthHistory:
      type: object
      additionalProperties: false
      properties:
        sessionId:
          type: string
          format: uuid
          description: |-
            Identifier of the connected Polymorfa session.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `uuid` |
        session:
          type: string
          description: Identifier of the connected Polymorfa session.
        points:
          type: array
          items:
            $ref: '#/components/schemas/management__BanSafeHealthPoint'
          description: Points associated with this management ban safe health history.
      required:
        - sessionId
        - session
        - points
    management__BanSafeHealthPoint:
      type: object
      additionalProperties: false
      properties:
        health:
          type: number
          minimum: 0
          maximum: 100
          nullable: true
          description: >-
            Specifies health for this management ban safe health point.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `number`; Numeric value: `0` through `100`
            (inclusive) |

            | Alternative 2 | `null` |


            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Numeric value | `0` through `100` (inclusive) |
        band:
          type: string
          enum:
            - good
            - fair
            - poor
            - failing
            - unknown
            - null
          nullable: true
          description: >-
            Specifies band for this management ban safe health point.


            <!-- polymorfa-input-table -->

            **Allowed values**

            | Value | Meaning |

            | --- | --- |

            | `good` | Good. |

            | `fair` | Fair. |

            | `poor` | Poor. |

            | `failing` | Failing. |

            | `unknown` | Unknown. |

            | `null` | Null. |


            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `string`; Value `good` or `fair` or `poor`
            or `failing` or `unknown` |

            | Alternative 2 | `null` |
        healthSource:
          type: string
          enum:
            - rules_v1
            - ml_model
            - unavailable
          description: |-
            Specifies health source for this management ban safe health point.

            <!-- polymorfa-input-table -->
            **Allowed values**
            | Value | Meaning |
            | --- | --- |
            | `rules_v1` | Rules v1. |
            | `ml_model` | Ml model. |
            | `unavailable` | Unavailable. |
        healthEstimatorVersion:
          type: string
          nullable: true
          description: >-
            Specifies health estimator version for this management ban safe
            health point.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `string` |

            | Alternative 2 | `null` |
        healthModelVersion:
          type: string
          nullable: true
          description: >-
            Specifies health model version for this management ban safe health
            point.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `string` |

            | Alternative 2 | `null` |
        healthEvaluatedAt:
          type: string
          format: date-time
          description: |-
            Timestamp for health evaluated at.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `date-time` |
        healthFeatureCoverage:
          type: number
          minimum: 0
          maximum: 1
          nullable: true
          description: >-
            Specifies health feature coverage for this management ban safe
            health point.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `number`; Numeric value: `0` through `1`
            (inclusive) |

            | Alternative 2 | `null` |


            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Numeric value | `0` through `1` (inclusive) |
        healthReliability:
          type: string
          enum:
            - rules_based
            - validated
            - unavailable
          description: >-
            Specifies health reliability for this management ban safe health
            point.


            <!-- polymorfa-input-table -->

            **Allowed values**

            | Value | Meaning |

            | --- | --- |

            | `rules_based` | Rules based. |

            | `validated` | Validated. |

            | `unavailable` | Unavailable. |
        healthUnavailableReason:
          type: string
          nullable: true
          enum:
            - no_active_model
            - invalid_active_model
            - insufficient_fresh_features
            - null
          description: >-
            Specifies health unavailable reason for this management ban safe
            health point.


            <!-- polymorfa-input-table -->

            **Allowed values**

            | Value | Meaning |

            | --- | --- |

            | `no_active_model` | No active model. |

            | `invalid_active_model` | Invalid active model. |

            | `insufficient_fresh_features` | Insufficient fresh features. |

            | `null` | Null. |


            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `string`; Value `no_active_model` or
            `invalid_active_model` or `insufficient_fresh_features` |

            | Alternative 2 | `null` |
        healthProbabilities:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/management__BanSafeHealthProbabilities'
          description: >-
            Specifies health probabilities for this management ban safe health
            point.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `object`; Required fields: `healthy`,
            `limited`, `restricted`, `banned` |

            | Alternative 2 | `null` |
        mostLikelyHealthState:
          type: string
          enum:
            - healthy
            - limited
            - restricted
            - banned
            - null
          nullable: true
          description: >-
            Specifies most likely health state for this management ban safe
            health point.


            <!-- polymorfa-input-table -->

            **Allowed values**

            | Value | Meaning |

            | --- | --- |

            | `healthy` | Healthy. |

            | `limited` | Limited. |

            | `restricted` | Restricted. |

            | `banned` | Banned. |

            | `null` | Null. |


            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `string`; Value `healthy` or `limited` or
            `restricted` or `banned` |

            | Alternative 2 | `null` |
        healthExplanation:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/management__BanSafeHealthExplanation'
          description: >-
            Specifies health explanation for this management ban safe health
            point.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `object`; Required fields: `penalties`,
            `factors`, `measuredGroups`, `missingGroups` |

            | Alternative 2 | `null` |
        observedAccountState:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/management__BanSafeObservedAccountState'
          description: >-
            Specifies observed account state for this management ban safe health
            point.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `object`; Field `state`: `healthy` or
            `limited` or `restricted` or `banned`; Field `source`:
            `account_check` or `restriction_event`; Required fields: `state`,
            `observedAt`, `source` |

            | Alternative 2 | `null` |
      required:
        - health
        - band
        - healthSource
        - healthEstimatorVersion
        - healthModelVersion
        - healthEvaluatedAt
        - healthFeatureCoverage
        - healthReliability
        - healthUnavailableReason
        - healthProbabilities
        - mostLikelyHealthState
        - healthExplanation
        - observedAccountState
    management__ErrorEnvelope:
      type: object
      required:
        - error
        - data
        - docs
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
            - param
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - conflict_error
                - rate_limit_error
                - api_error
                - upstream_error
              description: |-
                Type discriminator for this object.

                <!-- polymorfa-input-table -->
                **Allowed values**
                | Value | Meaning |
                | --- | --- |
                | `invalid_request_error` | Invalid request error. |
                | `authentication_error` | Authentication error. |
                | `permission_error` | Permission error. |
                | `conflict_error` | Conflict error. |
                | `rate_limit_error` | Rate limit error. |
                | `api_error` | Api error. |
                | `upstream_error` | Upstream error. |
            code:
              type: string
              description: Stable failure code. Use this value for programmatic handling.
            message:
              type: string
              description: Safe explanation of the failure.
            param:
              type: string
              nullable: true
              description: |-
                Invalid request field, or null when no field applies.

                <!-- polymorfa-input-table -->
                **Accepted alternatives**
                | Alternative | Accepted input |
                | --- | --- |
                | Alternative 1 | Type: `string` |
                | Alternative 2 | `null` |
          description: Error details returned when the operation fails.
        data:
          type: string
          nullable: true
          enum:
            - null
          description: |-
            Always null for a failed request.

            <!-- polymorfa-input-table -->
            **Allowed values**
            | Value | Meaning |
            | --- | --- |
            | `null` | Null. |

            **Accepted alternatives**
            | Alternative | Accepted input |
            | --- | --- |
            | Alternative 1 | Type: `string` |
            | Alternative 2 | `null` |
        docs:
          type: string
          format: uri
          description: |-
            Documentation link to this failure code.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `uri` |
    management__BanSafeHealthProbabilities:
      type: object
      additionalProperties: false
      properties:
        healthy:
          type: number
          minimum: 0
          maximum: 1
          description: |-
            Specifies healthy for this management ban safe health probability.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` through `1` (inclusive) |
        limited:
          type: number
          minimum: 0
          maximum: 1
          description: |-
            Specifies limited for this management ban safe health probability.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` through `1` (inclusive) |
        restricted:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Specifies restricted for this management ban safe health
            probability.


            <!-- polymorfa-input-table -->

            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Numeric value | `0` through `1` (inclusive) |
        banned:
          type: number
          minimum: 0
          maximum: 1
          description: |-
            Specifies banned for this management ban safe health probability.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` through `1` (inclusive) |
      required:
        - healthy
        - limited
        - restricted
        - banned
    management__BanSafeHealthExplanation:
      type: object
      additionalProperties: false
      description: >-
        Bounded rules-v1 inputs and deductions. It is not a forecast or
        confidence score.
      properties:
        penalties:
          type: object
          additionalProperties: false
          properties:
            conduct:
              type: number
              minimum: 0
              maximum: 100
              description: |-
                Specifies conduct for this penalty.

                <!-- polymorfa-input-table -->
                **Value constraints**
                | Constraint | Accepted input |
                | --- | --- |
                | Numeric value | `0` through `100` (inclusive) |
            delivery:
              type: number
              minimum: 0
              maximum: 100
              description: |-
                Specifies delivery for this penalty.

                <!-- polymorfa-input-table -->
                **Value constraints**
                | Constraint | Accepted input |
                | --- | --- |
                | Numeric value | `0` through `100` (inclusive) |
            connection:
              type: number
              minimum: 0
              maximum: 100
              description: |-
                Specifies connection for this penalty.

                <!-- polymorfa-input-table -->
                **Value constraints**
                | Constraint | Accepted input |
                | --- | --- |
                | Numeric value | `0` through `100` (inclusive) |
            restriction:
              type: number
              minimum: 0
              maximum: 100
              description: |-
                Specifies restriction for this penalty.

                <!-- polymorfa-input-table -->
                **Value constraints**
                | Constraint | Accepted input |
                | --- | --- |
                | Numeric value | `0` through `100` (inclusive) |
            total:
              type: number
              minimum: 0
              maximum: 100
              description: |-
                Final total for this order or price summary.

                <!-- polymorfa-input-table -->
                **Value constraints**
                | Constraint | Accepted input |
                | --- | --- |
                | Numeric value | `0` through `100` (inclusive) |
          required:
            - conduct
            - delivery
            - connection
            - restriction
            - total
          description: >-
            Structured penalties values for this management ban safe health
            explanation.
        factors:
          type: array
          maxItems: 8
          items:
            $ref: '#/components/schemas/management__BanSafeHealthExplanationFactor'
          description: |-
            Factors associated with this management ban safe health explanation.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Array size | At most `8` items |
        measuredGroups:
          type: array
          maxItems: 5
          uniqueItems: true
          items:
            type: string
            enum:
              - direct_condition
              - delivery
              - connection
              - conduct
              - cadence
          description: >-
            Measured groups associated with this management ban safe health
            explanation.


            <!-- polymorfa-input-table -->

            **Allowed item values**

            | Item value | Meaning |

            | --- | --- |

            | `direct_condition` | Direct condition. |

            | `delivery` | Delivery. |

            | `connection` | Connection. |

            | `conduct` | Conduct. |

            | `cadence` | Cadence. |


            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Array size | At most `5` items |

            | Duplicates | Not accepted; every array item must be unique |
        missingGroups:
          type: array
          maxItems: 5
          uniqueItems: true
          items:
            type: string
            enum:
              - direct_condition
              - delivery
              - connection
              - conduct
              - cadence
          description: >-
            Missing groups associated with this management ban safe health
            explanation.


            <!-- polymorfa-input-table -->

            **Allowed item values**

            | Item value | Meaning |

            | --- | --- |

            | `direct_condition` | Direct condition. |

            | `delivery` | Delivery. |

            | `connection` | Connection. |

            | `conduct` | Conduct. |

            | `cadence` | Cadence. |


            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Array size | At most `5` items |

            | Duplicates | Not accepted; every array item must be unique |
      required:
        - penalties
        - factors
        - measuredGroups
        - missingGroups
    management__BanSafeObservedAccountState:
      type: object
      additionalProperties: false
      description: Direct account-state evidence. This is not an ML estimate.
      properties:
        state:
          type: string
          enum:
            - healthy
            - limited
            - restricted
            - banned
          description: |-
            Current lifecycle state of this resource.

            <!-- polymorfa-input-table -->
            **Allowed values**
            | Value | Meaning |
            | --- | --- |
            | `healthy` | Healthy. |
            | `limited` | Limited. |
            | `restricted` | Restricted. |
            | `banned` | Banned. |
        observedAt:
          type: string
          format: date-time
          description: |-
            ISO 8601 timestamp when Polymorfa observed this state.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `date-time` |
        source:
          type: string
          enum:
            - account_check
            - restriction_event
          description: >-
            Specifies source for this management ban safe observed account
            state.


            <!-- polymorfa-input-table -->

            **Allowed values**

            | Value | Meaning |

            | --- | --- |

            | `account_check` | Account check. |

            | `restriction_event` | Restriction event. |
      required:
        - state
        - observedAt
        - source
    management__BanSafeHealthExplanationFactor:
      type: object
      additionalProperties: false
      description: >-
        One factual rules-v1 input. penalty is the number of Health points this
        input subtracts.
      properties:
        group:
          type: string
          enum:
            - direct_condition
            - delivery
            - connection
            - conduct
            - cadence
          description: >-
            Specifies group for this management ban safe health explanation
            factor.


            <!-- polymorfa-input-table -->

            **Allowed values**

            | Value | Meaning |

            | --- | --- |

            | `direct_condition` | Direct condition. |

            | `delivery` | Delivery. |

            | `connection` | Connection. |

            | `conduct` | Conduct. |

            | `cadence` | Cadence. |
        key:
          type: string
          enum:
            - observed_limited
            - observed_restricted
            - observed_banned
            - send_failures
            - receipt_errors
            - server_ack_tail
            - connection_failures
            - connection_churn
            - connection_disconnected
            - auto_reconnect_errors
            - keep_alive_errors
            - unanswered_first_contacts
            - unsolicited_sends
            - send_burst
            - fixed_send_rhythm
          description: >-
            Specifies key for this management ban safe health explanation
            factor.


            <!-- polymorfa-input-table -->

            **Allowed values**

            | Value | Meaning |

            | --- | --- |

            | `observed_limited` | Observed limited. |

            | `observed_restricted` | Observed restricted. |

            | `observed_banned` | Observed banned. |

            | `send_failures` | Send failures. |

            | `receipt_errors` | Receipt errors. |

            | `server_ack_tail` | Server ack tail. |

            | `connection_failures` | Connection failures. |

            | `connection_churn` | Connection churn. |

            | `connection_disconnected` | Connection disconnected. |

            | `auto_reconnect_errors` | Auto reconnect errors. |

            | `keep_alive_errors` | Keep alive errors. |

            | `unanswered_first_contacts` | Unanswered first contacts. |

            | `unsolicited_sends` | Unsolicited sends. |

            | `send_burst` | Send burst. |

            | `fixed_send_rhythm` | Fixed send rhythm. |
        penalty:
          type: number
          minimum: 0
          maximum: 100
          description: >-
            Specifies penalty for this management ban safe health explanation
            factor.


            <!-- polymorfa-input-table -->

            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Numeric value | `0` through `100` (inclusive) |
        observedValue:
          type: number
          description: >-
            Specifies observed value for this management ban safe health
            explanation factor.
        sampleSize:
          type: integer
          minimum: 0
          description: >-
            Specifies sample size for this management ban safe health
            explanation factor.


            <!-- polymorfa-input-table -->

            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Numeric value | `0` or greater |
      required:
        - group
        - key
        - penalty
        - observedValue
        - sampleSize
  responses:
    management__BadRequest:
      description: A path, query, or request-body value did not pass validation.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Stable request correlation identifier.
        Polymorfa-Version:
          schema:
            type: string
          description: API version applied to this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/management__ErrorEnvelope'
    management__Unauthorized:
      description: Missing/invalid credential for this audience.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Stable request correlation identifier.
        Polymorfa-Version:
          schema:
            type: string
          description: API version applied to this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/management__ErrorEnvelope'
    management__Forbidden:
      description: Authenticated but lacks the required scope/role/audience.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Stable request correlation identifier.
        Polymorfa-Version:
          schema:
            type: string
          description: API version applied to this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/management__ErrorEnvelope'
    management__NotFound:
      description: >-
        The requested resource was not found inside the authenticated
        organization or project scope.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Stable request correlation identifier.
        Polymorfa-Version:
          schema:
            type: string
          description: API version applied to this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/management__ErrorEnvelope'
  securitySchemes:
    management__ApiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Polymorfa server credential: a scoped pmfa_ organization key, or a
        pmfa_pt_ project token on project- and session-bound operations inside
        its exact authenticated project. Keys may be personal or service-account
        owned. Both enforce selected action scopes; organization keys can
        address team resources and every project in the organization. Listener
        and browser client credentials are rejected.

````