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

# Retrieve a subscription alert

> This endpoint enables the retrieval of a specific alert for a subscription.



## OpenAPI

````yaml /nozle-openapi.yaml get /subscriptions/{external_id}/alerts/{code}
openapi: 3.1.0
info:
  title: Nozle Billing API
  description: >-
    Nozle Billing API allows your application to push customer information and
    metrics (events) from your application to the billing engine.
  version: 1.49.0
  license:
    name: AGPLv3
    url: https://github.com/nozle-dev/core/blob/main/LICENSE
  contact:
    email: support@nozle.app
servers:
  - url: https://core.nozle.app/api/v1
    description: Nozle Billing API
security:
  - bearerAuth: []
tags:
  - name: Activity Logs
    description: Everything about Activity logs
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Analytics
    description: Everything about Analytics
  - name: API Logs
    description: Everything about API logs
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Features
    description: Everything about Feature collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Entitlements
    description: Everything about Entitlement collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Billing Entities
    description: Everything about Billing Entities
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Customers
    description: Everything about Customer collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Plans
    description: Everything about Plan collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Subscriptions
    description: Everything about Subscription collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Events
    description: Everything about Event collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Organizations
    description: Everything about Organization collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Taxes
    description: Everything about Tax collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Coupons
    description: Everything about Coupon collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Add-ons
    description: Everything about Add-on collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Fees
    description: Everything about Fees
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Invoices
    description: Everything about Invoice collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Wallets
    description: Everything about Wallet collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Credit Notes
    description: Everything about Credit notes collection
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Webhooks
    description: Everything about Webhooks
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Webhook Endpoints
    description: Everything about Webhook Endpoints
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Payment Receipts
    description: Everything about Payment receipts
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Payment Requests
    description: Everything about PaymentRequests
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Payments
    description: Everything about Payments
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
  - name: Payment Methods
    description: Everything about Payment Methods
    externalDocs:
      description: Find out more
      url: https://docs.nozle.app/api-reference
externalDocs:
  description: Nozle Github
  url: https://github.com/nozle-dev
paths:
  /subscriptions/{external_id}/alerts/{code}:
    parameters:
      - name: external_id
        in: path
        description: External ID of the existing subscription
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
      - name: code
        in: path
        description: Unique code of the alert
        required: true
        schema:
          type: string
          example: storage_threshold_alert
    get:
      tags:
        - Subscriptions
      summary: Retrieve a subscription alert
      description: >-
        This endpoint enables the retrieval of a specific alert for a
        subscription.
      operationId: getSubscriptionAlert
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Subscription alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    subscription_status:
      name: subscription_status
      in: query
      description: >
        Filter by subscription status. When provided, the subscription is looked
        up with this status instead of the default `active` status. Possible
        values are `pending`, `active`, `terminated`, or `canceled`.
      required: false
      schema:
        type: string
        enum:
          - pending
          - active
          - terminated
          - canceled
        default: active
        example: active
  schemas:
    Alert:
      type: object
      required:
        - alert
      properties:
        alert:
          $ref: '#/components/schemas/AlertObject'
    AlertObject:
      type: object
      required:
        - lago_id
        - lago_organization_id
        - external_subscription_id
        - feature
        - alert_type
        - code
        - name
        - previous_value
        - last_processed_at
        - thresholds
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the alert, created by Nozle.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_organization_id:
          type: string
          format: uuid
          description: Unique identifier of the organization, created by Nozle.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_subscription_id:
          type:
            - string
            - 'null'
          description: >-
            The subscription external unique identifier (provided by your own
            application).
          example: sub_1234567890
        lago_wallet_id:
          type: 'null'
        wallet_code:
          type: 'null'
        feature:
          $ref: '#/components/schemas/FeatureObject'
          description: >-
            The feature associated with the alert. Only for alerts based on a
            feature.
        alert_type:
          type: string
          description: The type of alert.
          enum:
            - current_usage_amount
            - feature_current_usage_amount
            - feature_current_usage_units
            - lifetime_usage_amount
          example: feature_current_usage_amount
        code:
          type: string
          description: Unique code used to identify the alert.
          example: storage_threshold_alert
        name:
          type:
            - string
            - 'null'
          description: The name of the alert.
          example: Storage Usage Alert
        direction:
          type: string
          description: >-
            Indicates whether the alert is triggered when the monitored metric
            goes above or below the threshold.
          enum:
            - increasing
            - decreasing
          example: increasing
        previous_value:
          type: number
          description: >-
            When the system checked if this alert should be triggered, this
            value was retrieved and checked against the thresholds.
          example: 1000
        last_processed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            The date and time in UTC (ISO 8601) when the system checked if this
            alert should be triggered. Null until it's processed for the first
            time.
          example: '2025-05-19T10:04:21Z'
        thresholds:
          type: array
          description: Array of thresholds associated with the alert.
          items:
            $ref: '#/components/schemas/AlertThresholdObject'
        created_at:
          type: string
          format: date-time
          description: The date and time in UTC (ISO 8601) when the alert was created.
          example: '2025-03-20T10:00:00Z'
    ApiErrorUnauthorized:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: integer
          format: int32
          example: 401
        error:
          type: string
          example: Unauthorized
    ApiErrorNotFound:
      type: object
      required:
        - status
        - error
        - code
      properties:
        status:
          type: integer
          format: int32
          example: 404
        error:
          type: string
          example: Not Found
        code:
          type: string
          example: object_not_found
    FeatureObject:
      type: object
      required:
        - lago_id
        - code
        - name
        - feature_type
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier of the Feature created by Nozle.
        code:
          type: string
          example: seats
          description: Immutable code used for entitlement checks and metered events.
        name:
          type: string
          example: Number of seats
          description: Name of the feature. Max 255 characters.
        description:
          type:
            - string
            - 'null'
          example: Number of users of the account
          description: Description of the feature. Max 600 characters.
        feature_type:
          type: string
          enum:
            - boolean
            - config
            - metered
          example: metered
          description: >-
            Determines which Feature configuration is active. Immutable after
            creation.
        privileges:
          type: array
          items:
            $ref: '#/components/schemas/FeaturePrivilegeObject'
          example:
            - code: max
              name: Maximum
              value_type: integer
              config: {}
            - code: max_admins
              name: Max Admins
              value_type: integer
              config: {}
            - code: root
              name: Allow root user
              value_type: boolean
              config: {}
            - code: provider
              name: SSO Provider
              value_type: select
              config:
                select_options:
                  - google
                  - okta
          description: >-
            Privileges for boolean and config Features. Config Features require
            at least one.
        aggregation_type:
          type:
            - string
            - 'null'
          enum:
            - count_agg
            - sum_agg
            - max_agg
            - unique_count_agg
            - weighted_sum_agg
            - latest_agg
            - custom_agg
            - null
          example: sum_agg
          description: Aggregation method for a metered Feature.
        consumable:
          type:
            - boolean
            - 'null'
          example: true
          description: >-
            Whether metered usage consumes an allowance or Credit System
            balance.
        recurring:
          type:
            - boolean
            - 'null'
          example: false
          description: Whether accumulated usage carries into the next billing period.
        field_name:
          type:
            - string
            - 'null'
          example: tokens
          description: Event property aggregated by the metered Feature.
        expression:
          type:
            - string
            - 'null'
          example: round((ended_at - started_at) * units)
        custom_aggregator:
          type:
            - string
            - 'null'
          description: >-
            Custom aggregation implementation when aggregation_type is
            custom_agg.
        weighted_interval:
          type:
            - string
            - 'null'
          enum:
            - seconds
            - null
        rounding_function:
          type:
            - string
            - 'null'
          enum:
            - ceil
            - floor
            - round
            - null
        rounding_precision:
          type:
            - integer
            - 'null'
          example: 2
        filters:
          type: array
          items:
            $ref: '#/components/schemas/FeatureFilterObject'
        created_at:
          type: string
          format: date-time
          example: '2025-07-17T12:34:35Z'
          description: Creation date of the feature.
    AlertThresholdObject:
      allOf:
        - $ref: '#/components/schemas/AlertThresholdBaseObject'
        - type: object
          required:
            - code
            - value
            - recurring
          properties:
            value:
              type: string
              pattern: ^[0-9]+.?[0-9]*$
              description: >-
                A value that should trigger this alert, formatted as a
                BigDecimal.
              example: '99.0'
    FeaturePrivilegeObject:
      type: object
      required:
        - code
        - name
        - value_type
        - config
      properties:
        code:
          type: string
          example: max
          description: Unique code for the privilege.
        name:
          type:
            - string
            - 'null'
          example: Maximum
          description: Display name for the privilege.
        value_type:
          type: string
          enum:
            - integer
            - boolean
            - string
            - select
          example: integer
          description: 'Data type of the privilege value. Default: string'
        config:
          type: object
          properties:
            select_options:
              type: array
              items:
                type: string
              example:
                - google
                - okta
              description: Array of string, required only when value_type is `select`.
    FeatureFilterObject:
      type: object
      description: Values used to segment metered Feature events.
      required:
        - key
        - values
      properties:
        key:
          type: string
          example: region
        values:
          type: array
          items:
            type: string
          example:
            - us-east-1
    AlertThresholdBaseObject:
      type: object
      properties:
        code:
          type:
            - string
            - 'null'
          description: Unique identifier of the usage threshold created by Nozle.
          example: warn
        recurring:
          type: boolean
          default: false
          description: >-
            This field when set to `true` indicates that the alert will be
            retrigger when this threshold is reached after the last
            non-recurring threshold. Only one recurring threshold per alert
            allowed.
          example: false
  responses:
    Unauthorized:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnauthorized'
    NotFound:
      description: Not Found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotFound'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````