> ## Documentation Index > Fetch the complete documentation index at: https://docs.withorb.com/llms.txt > Use this file to discover all available pages before exploring further. # List alerts > This endpoint returns a list of alerts within Orb. The request must specify one of `customer_id`, `external_customer_id`, or `subscription_id`. If querying by subscription_id, the endpoint will return the subscription level alerts as well as the plan level alerts associated with the subscription. The list of alerts is ordered starting from the most recently created alert. This endpoint follows Orb's [standardized pagination format](/api-reference/pagination). ## OpenAPI ````yaml /api-reference/orb-openapi.json get /alerts openapi: 3.1.0 info: title: API Reference description: >- Orb's API is built with the following principles in mind: 1. **Predictable developer experience**: Where applicable, the Orb API uses industry-standard patterns such as cursor-based pagination and standardized error output. To help with debugging in critical API actions, the API always strives to provide detailed and actionable error messages. Aliases such as external customer IDs aid in fast integration times. 2. **Reliably real time**: Orb's event-based APIs, such as event ingestion are designed to handle extremely high throughput and scale with concurrent load. Orb also provides a real-time event-level credits ledger and a highly performant webhooks architecture. 3. **Flexibility at the forefront**: Features like timezone localization and the ability to amend historical usage show the flexible nature of the platform. You can download the latest OpenAPI spec [here](https://api.withorb.com/spec.json) - pass `?version=3.0` for an OpenAPI 3.0-compatible spec. contact: name: Orb, Inc. url: https://www.withorb.com/ email: team@withorb.com version: '1.0' servers: - url: https://api.withorb.com/v1 description: Production server security: - APIKeyAuth: [] tags: - name: Alert description: >- [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending, usage, or credit balance and trigger webhooks when a threshold is exceeded. Alerts created through the API can be scoped to either customers or subscriptions. - name: Availability - name: Coupon description: >- A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users. - name: Credit description: >- The [Credit Ledger Entry resource](/product-catalog/prepurchase) models prepaid credits within Orb. - name: Credit note description: >- The [Credit Note](/invoicing/credit-notes) resource represents a credit that has been applied to a particular invoice. - name: Customer description: >- A customer is a buyer of your products, and the other party to the billing relationship. In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an `external_customer_id` with your own identifier. See [Customer ID Aliases](/events-and-metrics/customer-aliases) for further information about how these aliases work in Orb. In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the `payment_provider_id` and the `payment_provider` enum field to express this mapping. A customer also has a timezone (from the standard [IANA timezone database](https://www.iana.org/time-zones)), which defaults to your account's timezone. See [Timezone localization](/essentials/timezones) for information on what this timezone parameter influences within Orb. - name: Dimensional Price Group - name: Event description: >- The [Event](/core-concepts#event) resource represents a usage event that has been created for a customer. Events are the core of Orb's usage-based billing model, and are used to calculate the usage charges for a given billing period. - name: Invoice description: >- An [`Invoice`](/core-concepts#invoice) is a fundamental billing entity, representing the request for payment for a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and can represent fixed recurring fees or usage-based fees. They are generated at the end of a billing period, or as the result of an action, such as a cancellation. - name: Item description: >- The Item resource represents a sellable product or good. Items are associated with all line items, billable metrics, and prices and are used for defining external sync behavior for invoices and tax calculation purposes. - name: License - name: LicenseType description: >- The LicenseType resource represents a type of license that can be assigned to users. License types are used during billing by grouping metrics on the configured grouping key. - name: Metric description: >- The Metric resource represents a calculation of a quantity based on events. Metrics are defined by the query that transforms raw usage events into meaningful values for your customers. - name: Plan description: >- The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the [Price resource](/reference/price). - name: Price description: >- The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill. Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present. For more on the types of prices, see [the core concepts documentation](/core-concepts#plan-and-price) - name: Price interval description: >- The Price Interval resource represents a period of time for which a price will bill on a subscription. A subscription’s price intervals define its billing behavior. - name: Subscription description: >- A [subscription](/core-concepts#subscription) represents the purchase of a plan by a customer. By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition. Subscriptions also default to **beginning of month alignment**, which means the first invoice issued for the subscription will have pro-rated charges between the `start_date` and the first of the following month. Subsequent billing periods will always start and end on a month boundary (e.g. subsequent month starts for monthly billing). Depending on the plan configuration, any _flat_ recurring fees will be billed either at the beginning (in-advance) or end (in-arrears) of each billing cycle. Plans default to **in-advance billing**. Usage-based fees are billed in arrears as usage is accumulated. In the normal course of events, you can expect an invoice to contain usage-based charges for the previous period, and a recurring fee for the following period. - name: Subscription Change paths: /alerts: get: tags: - Alert summary: List alerts description: >- This endpoint returns a list of alerts within Orb. The request must specify one of `customer_id`, `external_customer_id`, or `subscription_id`. If querying by subscription_id, the endpoint will return the subscription level alerts as well as the plan level alerts associated with the subscription. The list of alerts is ordered starting from the most recently created alert. This endpoint follows Orb's [standardized pagination format](/api-reference/pagination). operationId: list-alerts parameters: - required: false style: form schema: type: integer maximum: 100 minimum: 1 title: Limit description: The number of items to fetch. Defaults to 20. default: 20 name: limit in: query - required: false style: form schema: oneOf: - type: string - type: 'null' title: Cursor description: >- Cursor for pagination. This can be populated by the `next_cursor` value returned from the initial request. name: cursor in: query - required: false style: form schema: oneOf: - type: string - type: 'null' title: Customer Id description: Fetch alerts scoped to this customer_id name: customer_id in: query - required: false style: form schema: oneOf: - type: string - type: 'null' title: External Customer Id description: Fetch alerts scoped to this external_customer_id name: external_customer_id in: query - required: false style: form schema: oneOf: - type: string - type: 'null' title: Subscription Id description: Fetch alerts scoped to this subscription_id name: subscription_id in: query - required: false style: form schema: oneOf: - type: string format: date-time - type: 'null' title: Created At[Gte] name: created_at[gte] in: query - required: false style: form schema: oneOf: - type: string format: date-time - type: 'null' title: Created At[Gt] name: created_at[gt] in: query - required: false style: form schema: oneOf: - type: string format: date-time - type: 'null' title: Created At[Lt] name: created_at[lt] in: query - required: false style: form schema: oneOf: - type: string format: date-time - type: 'null' title: Created At[Lte] name: created_at[lte] in: query responses: '200': description: OK headers: {} content: application/json: schema: $ref: '#/components/schemas/Alerts' '400': description: Bad Request headers: {} content: application/json: schema: $ref: '#/components/schemas/400Error' '401': description: Unauthorized headers: {} content: application/json: schema: $ref: '#/components/schemas/401Error' '404': description: Not Found headers: {} content: application/json: schema: $ref: '#/components/schemas/404Error' '409': description: Conflict headers: {} content: application/json: schema: $ref: '#/components/schemas/409Error' '413': description: Content Too Large headers: {} content: application/json: schema: $ref: '#/components/schemas/413Error' '429': description: Too Many Requests headers: {} content: application/json: schema: $ref: '#/components/schemas/429Error' '500': description: Internal Server Error headers: {} content: application/json: schema: $ref: '#/components/schemas/500Error' components: schemas: Alerts: properties: data: items: $ref: '#/components/schemas/Alert' type: array title: Data pagination_metadata: $ref: '#/components/schemas/PaginationMetadata' type: object required: - data - pagination_metadata title: Alerts 400Error: oneOf: - $ref: '#/components/schemas/ConstraintViolationError' - $ref: '#/components/schemas/DuplicateResourceCreationError' - $ref: '#/components/schemas/RequestValidationError' 401Error: $ref: '#/components/schemas/AuthorizationError' title: 401Error 404Error: oneOf: - $ref: '#/components/schemas/FeatureNotAvailableError' - $ref: '#/components/schemas/ResourceNotFoundError' - $ref: '#/components/schemas/URLNotFound' 409Error: $ref: '#/components/schemas/IdempotencyRequestMismatch' title: 409Error 413Error: oneOf: - $ref: '#/components/schemas/RequestTooLargeError' - $ref: '#/components/schemas/ResourceTooLargeError' - $ref: '#/components/schemas/TooManyResultsError' 429Error: $ref: '#/components/schemas/TooManyRequests' title: 429Error 500Error: $ref: '#/components/schemas/ServerError' title: 500Error Alert: properties: id: type: string title: Id description: Also referred to as alert_id in this documentation. examples: - XuxCbt7x9L82yyeF type: oneOf: - type: string enum: - credit_balance_depleted - credit_balance_dropped - credit_balance_recovered - type: string enum: - usage_exceeded - cost_exceeded - type: string enum: - license_balance_threshold_reached title: Type description: The type of alert. This must be a valid alert type. examples: - >- "usage_exceeded", "cost_exceeded", "credit_balance_depleted", "credit_balance_recovered", or "credit_balance_dropped" created_at: type: string format: date-time title: Created At description: The creation time of the resource in Orb. enabled: type: boolean title: Enabled description: Whether the alert is enabled or disabled. thresholds: oneOf: - items: $ref: '#/components/schemas/Threshold' type: array - type: 'null' title: Thresholds description: >- The thresholds that define the conditions under which the alert will be triggered. customer: oneOf: - $ref: '#/components/schemas/CustomerMinified' - type: 'null' description: The customer the alert applies to. plan: oneOf: - $ref: '#/components/schemas/PlanMinifiedWithVersion' - type: 'null' description: The plan the alert applies to. subscription: oneOf: - $ref: '#/components/schemas/SubscriptionMinified' - type: 'null' description: The subscription the alert applies to. metric: oneOf: - $ref: '#/components/schemas/BillableMetricMinified' - type: 'null' description: The metric the alert applies to. license_type: oneOf: - $ref: '#/components/schemas/LicenseTypeMinified' - type: 'null' description: >- The license type the alert applies to. Only present for license alerts. currency: oneOf: - type: string - type: 'null' title: Currency description: >- The name of the currency the credit balance or invoice cost is denominated in. grouping_keys: oneOf: - items: type: string type: array - type: 'null' title: Grouping Keys description: >- The property keys to group cost alerts by. Only present for cost alerts with grouping enabled. price_filters: oneOf: - items: $ref: '#/components/schemas/PriceFilter' type: array - type: 'null' title: Price Filters description: >- Filters scoping which prices are included in grouped cost alert evaluation. threshold_overrides: oneOf: - items: $ref: '#/components/schemas/ThresholdOverride' type: array - type: 'null' title: Threshold Overrides description: >- Per-group threshold overrides. Each override maps a specific combination of grouping_keys values to a replacement threshold list. Only present for grouped cost alerts that have at least one override. balance_alert_status: oneOf: - items: $ref: '#/components/schemas/BalanceAlertStatus' type: array - type: 'null' title: Balance Alert Status description: >- The current status of the alert. This field is only present for credit balance alerts. type: object required: - id - type - created_at - enabled - thresholds - customer - plan - subscription - metric - currency title: Alert description: >- [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending, usage, or credit balance and trigger webhooks when a threshold is exceeded. Alerts created through the API can be scoped to either customers or subscriptions. PaginationMetadata: properties: has_more: type: boolean title: Has More next_cursor: oneOf: - type: string - type: 'null' title: Next Cursor type: object required: - has_more - next_cursor title: PaginationMetadata ConstraintViolationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-constraint-violation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ConstraintViolationError DuplicateResourceCreationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: DuplicateResourceCreationError RequestValidationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-request-validation-errors title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title validation_errors: items: {} type: array title: Validation Errors type: object required: - type - status - validation_errors title: RequestValidationError AuthorizationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#401-authentication-error title: Type status: type: integer enum: - 401 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: AuthorizationError FeatureNotAvailableError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-feature-not-available title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: FeatureNotAvailableError ResourceNotFoundError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-resource-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: type: string title: Title type: object required: - type - status - title title: ResourceNotFoundError URLNotFound: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-url-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: URLNotFound IdempotencyRequestMismatch: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#409-resource-conflict title: Type status: type: integer enum: - 409 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: IdempotencyRequestMismatch RequestTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-request-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: RequestTooLargeError ResourceTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-resource-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ResourceTooLargeError TooManyResultsError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-too-many-results title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyResultsError TooManyRequests: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#429-too-many-requests title: Type status: type: integer enum: - 429 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyRequests ServerError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#500-internal-server-error title: Type status: type: integer title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ServerError Threshold: properties: value: type: number title: Value description: >- The value at which an alert will fire. For credit balance alerts, the alert will fire at or below this value. For usage and cost alerts, the alert will fire at or above this value. type: object required: - value title: Threshold description: >- Thresholds are used to define the conditions under which an alert will be triggered. CustomerMinified: properties: id: type: string title: Id external_customer_id: oneOf: - type: string - type: 'null' title: External Customer Id type: object required: - id - external_customer_id title: CustomerMinified PlanMinifiedWithVersion: properties: id: oneOf: - type: string - type: 'null' title: Id examples: - m2t5akQeh2obwxeU external_plan_id: oneOf: - type: string - type: 'null' title: External Plan Id description: >- An optional user-defined ID for this plan resource, used throughout the system as an alias for this Plan. Use this field to identify a plan by an existing identifier in your system. examples: - m2t5akQeh2obwxeU name: oneOf: - type: string - type: 'null' title: Name examples: - Example plan plan_version: type: string title: Plan Version type: object required: - id - external_plan_id - name - plan_version title: PlanMinifiedWithVersion SubscriptionMinified: properties: id: type: string title: Id examples: - VDGsT23osdLb84KD type: object required: - id title: SubscriptionMinified BillableMetricMinified: properties: id: type: string title: Id type: object required: - id title: BillableMetricMinified LicenseTypeMinified: properties: id: type: string title: Id type: object required: - id title: LicenseTypeMinified description: Minified license type for alert serialization. PriceFilter: properties: field: type: string enum: - price_id - item_id - price_type - currency - pricing_unit_id title: Field description: The property of the price to filter on. operator: type: string enum: - includes - excludes title: Operator description: Should prices that match the filter be included or excluded. values: items: type: string type: array uniqueItems: true title: Values description: The IDs or values that match this filter. type: object required: - field - operator - values title: PriceFilter ThresholdOverride: properties: group_values: items: type: string type: array title: Group Values description: >- The values of the grouping keys that identify this group. The list length matches the alert's grouping_keys. thresholds: items: $ref: '#/components/schemas/Threshold' type: array title: Thresholds description: >- The thresholds applied to this group. An empty list means the group is silenced. type: object required: - group_values - thresholds title: ThresholdOverride description: |- A per-group threshold override on a grouped cost alert. An empty `thresholds` list means the group is silenced (never fires). A non-empty list fully replaces the default thresholds for that group. BalanceAlertStatus: properties: threshold_value: type: number title: Threshold Value description: The value of the threshold that defines the alert status. in_alert: type: boolean title: In Alert description: Whether the alert is currently in-alert or not. type: object required: - threshold_value - in_alert title: BalanceAlertStatus description: >- Alert status is used to determine if an alert is currently in-alert or not. securitySchemes: APIKeyAuth: type: http description: API Keys can be issued in the Orb's web application. scheme: bearer ````