metronome-sdk 0.3.0 → 1.0.0

data/lib/metronome_sdk/resources/v1/customers.rb

@@ -28,7 +28,40 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerCreateParams} for more details.
         #
-        # Create a new customer
+        # Create a new customer in Metronome and optionally the billing configuration
+        # (recommended) which dictates where invoices for the customer will be sent or
+        # where payment will be collected.
+        #
+        # ### Use this endpoint to:
+        #
+        # Execute your customer provisioning workflows for either PLG motions, where
+        # customers originate in your platform, or SLG motions, where customers originate
+        # in your sales system.
+        #
+        # ### Key response fields:
+        #
+        # This end-point returns the `customer_id` created by the request. This id can be
+        # used to fetch relevant billing configurations and create contracts.
+        #
+        # ### Example workflow:
+        #
+        # - Generally, Metronome recommends first creating the customer in the downstream
+        #   payment / ERP system when payment method is collected and then creating the
+        #   customer in Metronome using the response (i.e. `customer_id`) from the
+        #   downstream system. If you do not create a billing configuration on customer
+        #   creation, you can add it later.
+        # - Once a customer is created, you can then create a contract for the customer.
+        #   In the contract creation process, you will need to add the customer billing
+        #   configuration to the contract to ensure Metronome invoices the customer
+        #   correctly. This is because a customer can have multiple configurations.
+        # - As part of the customer creation process, set the ingest alias for the
+        #   customer which will ensure usage is accurately mapped to the customer. Ingest
+        #   aliases can be added or changed after the creation process as well.
+        #
+        # ### Usage guidelines:
+        #
+        # For details on different billing configurations for different systems, review
+        # the `/setCustomerBillingConfiguration` end-point.
         #
         # @overload create(name:, billing_config: nil, custom_fields: nil, customer_billing_provider_configurations: nil, external_id: nil, ingest_aliases: nil, request_options: {})
         #
@@ -36,7 +69,7 @@ module MetronomeSDK
         #
         # @param billing_config [MetronomeSDK::Models::V1::CustomerCreateParams::BillingConfig]
         #
-        # @param custom_fields [Hash{Symbol=>String}]
+        # @param custom_fields [Hash{Symbol=>String}] Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
         #
         # @param customer_billing_provider_configurations [Array<MetronomeSDK::Models::V1::CustomerCreateParams::CustomerBillingProviderConfiguration>]
         #
@@ -60,7 +93,13 @@ module MetronomeSDK
           )
         end
 
-        # Get a customer by Metronome ID.
+        # Get detailed information for a specific customer by their Metronome ID. Returns
+        # customer profile data including name, creation date, ingest aliases,
+        # configuration settings, and custom fields. Use this endpoint to fetch complete
+        # customer details for billing operations or account management.
+        #
+        # Note: If searching for a customer billing configuration, use the
+        # `/getCustomerBillingConfigurations` endpoint.
         #
         # @overload retrieve(customer_id:, request_options: {})
         #
@@ -87,7 +126,11 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerListParams} for more details.
         #
-        # List all customers.
+        # Gets a paginated list of all customers in your Metronome account. Use this
+        # endpoint to browse your customer base, implement customer search functionality,
+        # or sync customer data with external systems. Returns customer details including
+        # IDs, names, and configuration settings. Supports filtering and pagination
+        # parameters for efficient data retrieval.
         #
         # @overload list(customer_ids: nil, ingest_alias: nil, limit: nil, next_page: nil, only_archived: nil, salesforce_account_ids: nil, request_options: {})
         #
@@ -120,8 +163,20 @@ module MetronomeSDK
           )
         end
 
-        # Archive a customer Note: any alerts associated with the customer will not be
-        # triggered.
+        # Use this endpoint to archive a customer while preserving auditability. Archiving
+        # a customer will automatically archive all contracts as of the current date and
+        # void all corresponding invoices. Use this endpoint if a customer is onboarded by
+        # mistake.
+        #
+        # ### Usage guidelines:
+        #
+        # - Once a customer is archived, it cannot be unarchived.
+        # - Archived customers can still be viewed through the API or the UI for audit
+        #   purposes.
+        # - Ingest aliases remain idempotent for archived customers. In order to reuse an
+        #   ingest alias, first remove the ingest alias from the customer prior to
+        #   archiving.
+        # - Any alerts associated with the customer will no longer be triggered.
         #
         # @overload archive(id:, request_options: {})
         #
@@ -145,7 +200,10 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerListBillableMetricsParams} for more details.
         #
-        # Get all billable metrics for a given customer.
+        # Get all billable metrics available for a specific customer. Supports pagination
+        # and filtering by current plan status or archived metrics. Use this endpoint to
+        # see which metrics are being tracked for billing calculations for a given
+        # customer.
         #
         # @overload list_billable_metrics(customer_id:, include_archived: nil, limit: nil, next_page: nil, on_current_plan: nil, request_options: {})
         #
@@ -255,9 +313,101 @@ module MetronomeSDK
           )
         end
 
-        # Sets the ingest aliases for a customer. Ingest aliases can be used in the
-        # `customer_id` field when sending usage events to Metronome. This call is
-        # idempotent. It fully replaces the set of ingest aliases for the given customer.
+        # Returns all billing configurations previously set for the customer. Use during
+        # the contract provisioning process to fetch the
+        # `billing_provider_configuration_id` needed to set the contract billing
+        # configuration.
+        #
+        # @overload retrieve_billing_configurations(customer_id:, include_archived: nil, request_options: {})
+        #
+        # @param customer_id [String]
+        # @param include_archived [Boolean]
+        # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [MetronomeSDK::Models::V1::CustomerRetrieveBillingConfigurationsResponse]
+        #
+        # @see MetronomeSDK::Models::V1::CustomerRetrieveBillingConfigurationsParams
+        def retrieve_billing_configurations(params)
+          parsed, options = MetronomeSDK::V1::CustomerRetrieveBillingConfigurationsParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "v1/getCustomerBillingProviderConfigurations",
+            body: parsed,
+            model: MetronomeSDK::Models::V1::CustomerRetrieveBillingConfigurationsResponse,
+            options: options
+          )
+        end
+
+        # Create a billing configuration for a customer. Once created, these
+        # configurations are available to associate to a contract and dictates which
+        # downstream system to collect payment in or send the invoice to. You can create
+        # multiple configurations per customer. The configuration formats are distinct for
+        # each downstream provider.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Add the initial configuration to an existing customer. Once created, the
+        #   billing configuration can then be associated to the customer's contract.
+        # - Add a new configuration to an existing customer. This might be used as part of
+        #   an upgrade or downgrade workflow where the customer was previously billed
+        #   through system A (e.g. Stripe) but will now be billed through system B (e.g.
+        #   AWS). Once created, the new configuration can then be associated to the
+        #   customer's contract.
+        #
+        # ### Delivery method options:
+        #
+        # - `direct_to_billing_provider`: Use when Metronome should send invoices directly
+        #   to the billing provider's API (e.g., Stripe, NetSuite). This is the most
+        #   common method for automated billing workflows.
+        # - `tackle`: Use specifically for AWS Marketplace transactions that require
+        #   Tackle's co-selling platform for partner attribution and commission tracking.
+        # - `aws_sqs`: Use when you want invoice data delivered to an AWS SQS queue for
+        #   custom processing before sending to your billing system.
+        # - `aws_sns`: Use when you want invoice notifications published to an AWS SNS
+        #   topic for event-driven billing workflows.
+        #
+        # ### Key response fields:
+        #
+        # The id for the customer billing configuration. This id can be used to associate
+        # the billing configuration to a contract.
+        #
+        # ### Usage guidelines:
+        #
+        # Must use the `delivery_method_id` if you have multiple Stripe accounts connected
+        # to Metronome.
+        #
+        # @overload set_billing_configurations(data:, request_options: {})
+        #
+        # @param data [Array<MetronomeSDK::Models::V1::CustomerSetBillingConfigurationsParams::Data>]
+        # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see MetronomeSDK::Models::V1::CustomerSetBillingConfigurationsParams
+        def set_billing_configurations(params)
+          parsed, options = MetronomeSDK::V1::CustomerSetBillingConfigurationsParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "v1/setCustomerBillingProviderConfigurations",
+            body: parsed,
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Sets the ingest aliases for a customer. Use this endpoint to associate a
+        # Metronome customer with an internal ID for easier tracking between systems.
+        # Ingest aliases can be used in the `customer_id` field when sending usage events
+        # to Metronome.
+        #
+        # ### Usage guidelines:
+        #
+        # - This call is idempotent and fully replaces the set of ingest aliases for the
+        #   given customer.
+        # - Switching an ingest alias from one customer to another will associate all
+        #   corresponding usage to the new customer.
+        # - Use multiple ingest aliases to model child organizations within a single
+        #   Metronome customer.
         #
         # @overload set_ingest_aliases(customer_id:, ingest_aliases:, request_options: {})
         #
@@ -288,7 +438,11 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerSetNameParams} for more details.
         #
-        # Updates the specified customer's name.
+        # Updates the display name for a customer record. Use this to correct customer
+        # names, update business names after rebranding, or maintain accurate customer
+        # information for invoicing and reporting. Returns the updated customer object
+        # with the new name applied immediately across all billing documents and
+        # interfaces.
         #
         # @overload set_name(customer_id:, name:, request_options: {})
         #
@@ -319,7 +473,10 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerUpdateConfigParams} for more details.
         #
-        # Updates the specified customer's config.
+        # Update configuration settings for a specific customer, such as external system
+        # integrations (e.g., Salesforce account ID) and other customer-specific billing
+        # parameters. Use this endpoint to modify customer configurations without
+        # affecting core customer data like name or ingest aliases.
         #
         # @overload update_config(customer_id:, leave_stripe_invoices_in_draft: nil, salesforce_account_id: nil, request_options: {})
         #

data/lib/metronome_sdk/resources/v1/dashboards.rb

@@ -4,9 +4,35 @@ module MetronomeSDK
   module Resources
     class V1
       class Dashboards
-        # Retrieve an embeddable dashboard url for a customer. The dashboard can be
-        # embedded using an iframe in a website. This will show information such as usage
-        # data and customer invoices.
+        # Generate secure, embeddable dashboard URLs that allow you to seamlessly
+        # integrate Metronome's billing visualizations directly into your application.
+        # This endpoint creates authenticated iframe-ready URLs for customer-specific
+        # dashboards, providing a white-labeled billing experience without building custom
+        # UI.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Embed billing dashboards directly in your customer portal or admin interface
+        # - Provide self-service access to invoices, usage data, and credit balances
+        # - Build white-labeled billing experiences with minimal development effort
+        #
+        # ### Key response fields:
+        #
+        # - A secure, time-limited URL that can be embedded in an iframe
+        # - The URL includes authentication tokens and configuration parameters
+        # - URLs are customer-specific and respect your security settings
+        #
+        # ### Usage guidelines:
+        #
+        # - Dashboard types: Choose from `invoices`, `usage`, or `commits_and_credits`
+        # - Customization options:
+        #   - `dashboard_options`: Configure whether you want invoices to show zero usage
+        #     line items
+        #   - `color_overrides`: Match your brand's color palette
+        #   - `bm_group_key_overrides`: Customize how dimensions are displayed (for the
+        #     usage embeddable dashboard)
+        # - Iframe implementation: Embed the returned URL directly in an iframe element
+        # - Responsive design: Dashboards automatically adapt to container dimensions
         #
         # @overload get_embeddable_url(customer_id:, dashboard:, bm_group_key_overrides: nil, color_overrides: nil, dashboard_options: nil, request_options: {})
         #

data/lib/metronome_sdk/resources/v1/invoices.rb

@@ -4,7 +4,24 @@ module MetronomeSDK
   module Resources
     class V1
       class Invoices
-        # Regenerate a voided contract invoice
+        # This endpoint regenerates a voided invoice and recalculates the invoice based on
+        # up-to-date rates, available balances, and other fees regardless of the billing
+        # period.
+        #
+        # ### Use this endpoint to:
+        #
+        # Recalculate an invoice with updated rate terms, available balance, and fees to
+        # correct billing disputes or discrepancies
+        #
+        # ### Key response fields:
+        #
+        # The regenerated invoice id, which is distinct from the previously voided
+        # invoice.
+        #
+        # ### Usage guidelines:
+        #
+        # If an invoice is attached to a contract with a billing provider on it, the
+        # regenerated invoice will be distributed based on the configuration.
         #
         # @overload regenerate(id:, request_options: {})
         #
@@ -26,7 +43,11 @@ module MetronomeSDK
           )
         end
 
-        # Void an invoice
+        # Permanently cancels an invoice by setting its status to voided, preventing
+        # collection and removing it from customer billing. Use this to correct billing
+        # errors, cancel incorrect charges, or handle disputed invoices that should not be
+        # collected. Returns the voided invoice ID with the status change applied
+        # immediately to stop any payment processing.
         #
         # @overload void(id:, request_options: {})
         #

data/lib/metronome_sdk/resources/v1/pricing_units.rb

@@ -4,7 +4,12 @@ module MetronomeSDK
   module Resources
     class V1
       class PricingUnits
-        # List all pricing units (known in the API by the legacy term "credit types").
+        # List all pricing units. All fiat currency types (for example, USD or GBP) will
+        # be included, as well as any custom pricing units that were configured. Custom
+        # pricing units can be used to charge for usage in a non-fiat pricing unit, for
+        # example AI credits.
+        #
+        # Note: The USD (cents) pricing unit is 2714e483-4ff1-48e4-9e25-ac732e8f24f2.
         #
         # @overload list(limit: nil, next_page: nil, request_options: {})
         #

data/lib/metronome_sdk/resources/v1/services.rb

@@ -4,10 +4,12 @@ module MetronomeSDK
   module Resources
     class V1
       class Services
-        # Fetches a list of services used by Metronome and the associated IP addresses. IP
-        # addresses are not necessarily unique between services. In most cases, IP
-        # addresses will appear in the list at least 30 days before they are used for the
-        # first time.
+        # Gets Metronome's service registry with associated IP addresses for security
+        # allowlisting and firewall configuration. Use this endpoint to maintain an
+        # up-to-date list of IPs that your systems should trust for Metronome
+        # communications. Returns service names and their current IP ranges, with new IPs
+        # typically appearing 30+ days before first use to ensure smooth allowlist
+        # updates.
         #
         # @overload list(request_options: {})
         #

data/lib/metronome_sdk/resources/v1/usage.rb

@@ -7,8 +7,39 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::UsageListParams} for more details.
         #
-        # Fetch aggregated usage data for multiple customers and billable-metrics, broken
-        # into intervals of the specified length.
+        # Retrieve aggregated usage data across multiple customers and billable metrics in
+        # a single query. This batch endpoint enables you to fetch usage patterns at
+        # scale, broken down by time windows, making it ideal for building analytics
+        # dashboards, generating reports, and monitoring platform-wide usage trends.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Generate platform-wide usage reports for internal teams
+        # - Monitor aggregate usage trends across your entire customer base
+        # - Create comparative usage analyses between customers or time periods
+        # - Support capacity planning with historical usage patterns
+        #
+        # ### Key response fields:
+        #
+        # An array of `UsageBatchAggregate` objects containing:
+        #
+        # - `customer_id`: The customer this usage belongs to
+        # - `billable_metric_id` and `billable_metric_name`: What was measured
+        # - `start_timestamp` and `end_timestamp`: Time window for this data point
+        # - `value`: Aggregated usage amount for the period
+        # - `groups` (optional): Usage broken down by group keys with values
+        # - `next_page`: Pagination cursor for large result sets
+        #
+        # ### Usage guidelines:
+        #
+        # - Time windows: Set `window_size` to `hour`, `day`, or `none` (entire period)
+        # - Required parameters: Must specify `starting_on`, `ending_before`, and
+        #   `window_size`
+        # - Filtering options:
+        #   - `customer_ids`: Limit to specific customers (omit for all customers)
+        #   - `billable_metrics`: Limit to specific metrics (omit for all metrics)
+        # - Pagination: Use `next_page` cursor to retrieve large datasets
+        # - Null values: Group values may be null when no usage matches that group
         #
         # @overload list(ending_before:, starting_on:, window_size:, next_page: nil, billable_metrics: nil, customer_ids: nil, request_options: {})
         #
@@ -26,7 +57,7 @@ module MetronomeSDK
         #
         # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
         #
-        # @return [MetronomeSDK::Models::V1::UsageListResponse]
+        # @return [MetronomeSDK::Internal::CursorPageWithoutLimit<MetronomeSDK::Models::V1::UsageListResponse>]
         #
         # @see MetronomeSDK::Models::V1::UsageListParams
         def list(params)
@@ -37,17 +68,97 @@ module MetronomeSDK
             path: "v1/usage",
             query: parsed.slice(*query_params),
             body: parsed.except(*query_params),
+            page: MetronomeSDK::Internal::CursorPageWithoutLimit,
             model: MetronomeSDK::Models::V1::UsageListResponse,
             options: options
           )
         end
 
-        # Send usage events to Metronome. The body of this request is expected to be a
-        # JSON array of between 1 and 100 usage events. Compressed request bodies are
-        # supported with a `Content-Encoding: gzip` header. See
+        # The ingest endpoint is the primary method for sending usage events to Metronome,
+        # serving as the foundation for all billing calculations in your usage-based
+        # pricing model. This high-throughput endpoint is designed for real-time streaming
+        # ingestion, supports backdating 34 days, and is built to handle mission-critical
+        # usage data with enterprise-grade reliability. Metronome supports 100,000 events
+        # per second without requiring pre-aggregation or rollups and can scale up from
+        # there. See
         # [Getting usage into Metronome](https://docs.metronome.com/connect-metronome/) to
         # learn more about usage events.
         #
+        # ### Use this endpoint to:
+        #
+        # Create a customer usage pipeline into Metronome that drives billable metrics,
+        # credit drawdown, and invoicing. Track customer behavior, resource consumption,
+        # and feature usage
+        #
+        # ### What happens when you send events:
+        #
+        # - Events are validated and processed in real-time
+        # - Events are matched to customers using customer IDs or customer ingest aliases
+        # - Events are matched to billable metrics and are immediately available for usage
+        #   and spend calculations
+        #
+        # ### Usage guidelines:
+        #
+        # - Historical events can be backdated up to 34 days and will immediately impact
+        #   live customer spend
+        # - Duplicate events are automatically detected and ignored (34-day deduplication
+        #   window)
+        #
+        # #### Event structure:
+        #
+        # Usage events are simple JSON objects designed for flexibility and ease of
+        # integration:
+        #
+        # ```json
+        # {
+        #   "transaction_id": "2021-01-01T00:00:00Z_cluster42",
+        #   "customer_id": "team@example.com",
+        #   "event_type": "api_request",
+        #   "timestamp": "2021-01-01T00:00:00Z",
+        #   "properties": {
+        #     "endpoint": "/v1/users",
+        #     "method": "POST",
+        #     "response_time_ms": 45,
+        #     "region": "us-west-2"
+        #   }
+        # }
+        # ```
+        #
+        # #### Transaction ID
+        #
+        # The transaction_id serves as your idempotency key, ensuring events are processed
+        # exactly once. Metronome maintains a 34-day deduplication window - significantly
+        # longer than typical 12-hour windows - enabling robust backfill scenarios without
+        # duplicate billing.
+        #
+        # - Best Practices:
+        #   - Use UUIDs for one-time events: uuid4()
+        #   - For heartbeat events, use deterministic IDs
+        #   - Include enough context to avoid collisions across different event sources
+        #
+        # #### Customer ID
+        #
+        # Identifies which customer should be billed for this usage. Supports two
+        # identification methods:
+        #
+        # - Metronome Customer ID: The UUID returned when creating a customer
+        # - Ingest Alias: Your system's identifier (email, account number, etc.)
+        #
+        # Ingest aliases enable seamless integration without requiring ID mapping, and
+        # customers can have multiple aliases for flexibility.
+        #
+        # #### Event Type:
+        #
+        # Categorizes the event type for billable metric matching. Choose descriptive
+        # names that aligns with the product surface area.
+        #
+        # #### Properties:
+        #
+        # Flexible metadata also used to match billable metrics or to be used to serve as
+        # group keys to create multiple pricing dimensions or breakdown costs by novel
+        # properties for end customers or internal finance teams measuring underlying
+        # COGs.
+        #
         # @overload ingest(usage: nil, request_options: {})
         #
         # @param usage [Array<MetronomeSDK::Models::V1::UsageIngestParams::Usage>]
@@ -70,8 +181,40 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::UsageListWithGroupsParams} for more details.
         #
-        # Fetch aggregated usage data for the specified customer, billable-metric, and
-        # optional group, broken into intervals of the specified length.
+        # Retrieve granular usage data for a specific customer and billable metric, with
+        # the ability to break down usage by custom grouping dimensions. This endpoint
+        # enables deep usage analytics by segmenting data across attributes like region,
+        # user, model type, or any custom dimension defined in your billable metrics.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Analyze usage patterns broken down by specific attributes (region, user,
+        #   department, etc.)
+        # - Build detailed usage dashboards with dimensional filtering
+        # - Identify high-usage segments for optimization opportunities
+        #
+        # ### Key response fields:
+        #
+        # An array of `PagedUsageAggregate` objects containing:
+        #
+        # - `starting_on` and `ending_before`: Time window boundaries
+        # - `group_key`: The dimension being grouped by (e.g., "region")
+        # - `group_value`: The specific value for this group (e.g., "US-East")
+        # - `value`: Aggregated usage for this group and time window
+        # - `next_page`: Pagination cursor for large datasets
+        #
+        # ### Usage guidelines:
+        #
+        # - Required parameters: Must specify `customer_id`, `billable_metric_id`, and
+        #   `window_size`
+        # - Time windows: Set `window_size` to hour, day, or none for different
+        #   granularities
+        # - Group filtering: Use `group_by` to specify:
+        #   - key: The dimension to group by (must be set on the billable metric as a
+        #     group key)
+        #   - values: Optional array to filter to specific values only
+        # - Pagination: Use limit and `next_page` for large result sets
+        # - Null handling: `group_value` may be null for unmatched data
         #
         # @overload list_with_groups(billable_metric_id:, customer_id:, window_size:, limit: nil, next_page: nil, current_period: nil, ending_before: nil, group_by: nil, starting_on: nil, request_options: {})
         #
@@ -112,10 +255,40 @@ module MetronomeSDK
           )
         end
 
-        # For a set of events, look up matched billable metrics and customers by
-        # transaction id. This endpoint looks at transactions that occurred in the last 34
-        # days, and is intended for sampling-based testing workflows. It is heavily rate
-        # limited.
+        # This endpoint retrieves events by transaction ID for events that occurred within
+        # the last 34 days. It is specifically designed for sampling-based testing
+        # workflows to detect revenue leakage. The Event Search API provides a critical
+        # observability tool that validates the integrity of your usage pipeline by
+        # allowing you to sample raw events and verify their matching against active
+        # billable metrics.
+        #
+        # Why event observability matters for revenue leakage: Silent revenue loss occurs
+        # when events are dropped, delayed, or fail to match billable metrics due to:
+        #
+        # - Upstream system failures
+        # - Event format changes
+        # - Misconfigured billable metrics
+        #
+        # ### Use this endpoint to:
+        #
+        # - Sample raw events and validate they match the expected billable metrics
+        # - Build custom leakage detection alerts to prevent silent revenue loss
+        # - Verify event processing accuracy during system changes or metric updates
+        # - Debug event matching issues in real-time
+        #
+        # ### Key response fields:
+        #
+        # - Complete event details including transaction ID, customer ID, and properties
+        # - Matched Metronome customer (if any)
+        # - Matched billable metric information (if any)
+        # - Processing status and duplicate detection flags
+        #
+        # ### Usage guidelines:
+        #
+        # ⚠️ Important: This endpoint is heavily rate limited and designed for sampling
+        # workflows only. Do not use this endpoint to check every event in your system.
+        # Instead, implement a sampling strategy to randomly validate a subset of events
+        # for observability purposes.
         #
         # @overload search(transaction_ids:, request_options: {})
         #