@metronome/sdk 0.3.0 → 2.0.0

package/resources/v1/usage.d.ts

@@ -1,46 +1,186 @@
-import { APIResource } from "../../resource.js";
-import * as Core from "../../core.js";
+import { APIResource } from "../../core/resource.js";
 import * as Shared from "../shared.js";
-import { CursorPage, type CursorPageParams } from "../../pagination.js";
+import { APIPromise } from "../../core/api-promise.js";
+import { CursorPage, type CursorPageParams, CursorPageWithoutLimit, type CursorPageWithoutLimitParams, PagePromise } from "../../core/pagination.js";
+import { RequestOptions } from "../../internal/request-options.js";
 export declare class Usage extends APIResource {
     /**
-     * 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
      *
      * @example
      * ```ts
-     * const usages = await client.v1.usage.list({
+     * // Automatically fetches more pages as needed.
+     * for await (const usageListResponse of client.v1.usage.list({
      *   ending_before: '2021-01-03T00:00:00Z',
      *   starting_on: '2021-01-01T00:00:00Z',
      *   window_size: 'day',
-     * });
+     * })) {
+     *   // ...
+     * }
      * ```
      */
-    list(params: UsageListParams, options?: Core.RequestOptions): Core.APIPromise<UsageListResponse>;
+    list(params: UsageListParams, options?: RequestOptions): PagePromise<UsageListResponsesCursorPageWithoutLimit, UsageListResponse>;
     /**
-     * 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
-     * [Getting usage into Metronome](https://docs.metronome.com/connect-metronome/) to
+     * 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 the [Send usage events](/guides/events/send-usage-events) guide 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"
+     *   }
+     * }
+     * ```
+     *
+     * Learn more about
+     * [usage event structure definitions](/guides/events/design-usage-events).
+     *
+     * #### 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.
+     *
      * @example
      * ```ts
-     * await client.v1.usage.ingest([
-     *   {
-     *     customer_id: 'team@example.com',
-     *     event_type: 'heartbeat',
-     *     timestamp: '2021-01-01T00:00:00Z',
-     *     transaction_id: '2021-01-01T00:00:00Z_cluster42',
-     *   },
-     * ]);
+     * await client.v1.usage.ingest();
      * ```
      */
-    ingest(body?: UsageIngestParams, options?: Core.RequestOptions): Core.APIPromise<void>;
-    ingest(options?: Core.RequestOptions): Core.APIPromise<void>;
+    ingest(params?: UsageIngestParams | null | undefined, options?: RequestOptions): APIPromise<void>;
     /**
-     * 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
      *
      * @example
      * ```ts
@@ -63,12 +203,42 @@ export declare class Usage extends APIResource {
      * }
      * ```
      */
-    listWithGroups(params: UsageListWithGroupsParams, options?: Core.RequestOptions): Core.PagePromise<UsageListWithGroupsResponsesCursorPage, UsageListWithGroupsResponse>;
+    listWithGroups(params: UsageListWithGroupsParams, options?: RequestOptions): PagePromise<UsageListWithGroupsResponsesCursorPage, UsageListWithGroupsResponse>;
     /**
-     * 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.
      *
      * @example
      * ```ts
@@ -77,30 +247,24 @@ export declare class Usage extends APIResource {
      * });
      * ```
      */
-    search(body: UsageSearchParams, options?: Core.RequestOptions): Core.APIPromise<UsageSearchResponse>;
-}
-export declare class UsageListWithGroupsResponsesCursorPage extends CursorPage<UsageListWithGroupsResponse> {
+    search(body: UsageSearchParams, options?: RequestOptions): APIPromise<UsageSearchResponse>;
 }
+export type UsageListResponsesCursorPageWithoutLimit = CursorPageWithoutLimit<UsageListResponse>;
+export type UsageListWithGroupsResponsesCursorPage = CursorPage<UsageListWithGroupsResponse>;
 export interface UsageListResponse {
-    data: Array<UsageListResponse.Data>;
-    next_page: string | null;
-}
-export declare namespace UsageListResponse {
-    interface Data {
-        billable_metric_id: string;
-        billable_metric_name: string;
-        customer_id: string;
-        end_timestamp: string;
-        start_timestamp: string;
-        value: number | null;
-        /**
-         * Values will be either a number or null. Null indicates that there were no
-         * matches for the group_by value.
-         */
-        groups?: {
-            [key: string]: number | null;
-        };
-    }
+    billable_metric_id: string;
+    billable_metric_name: string;
+    customer_id: string;
+    end_timestamp: string;
+    start_timestamp: string;
+    value: number | null;
+    /**
+     * Values will be either a number or null. Null indicates that there were no
+     * matches for the group_by value.
+     */
+    groups?: {
+        [key: string]: number | null;
+    };
 }
 export interface UsageListWithGroupsResponse {
     ending_before: string;
@@ -158,6 +322,9 @@ export declare namespace UsageSearchResponse {
              * provided, the billable metric is not archived.
              */
             archived_at?: string;
+            /**
+             * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+             */
             custom_fields?: {
                 [key: string]: string;
             };
@@ -200,7 +367,7 @@ export declare namespace UsageSearchResponse {
         }
     }
 }
-export interface UsageListParams {
+export interface UsageListParams extends CursorPageWithoutLimitParams {
     /**
      * Body param:
      */
@@ -216,10 +383,6 @@ export interface UsageListParams {
      * period.
      */
     window_size: 'HOUR' | 'DAY' | 'NONE';
-    /**
-     * Query param: Cursor that indicates where the next page of results should start.
-     */
-    next_page?: string;
     /**
      * Body param: A list of billable metrics to fetch usage for. If absent, all
      * billable metrics will be returned.
@@ -250,7 +413,9 @@ export declare namespace UsageListParams {
         }
     }
 }
-export type UsageIngestParams = Array<UsageIngestParams.Usage>;
+export interface UsageIngestParams {
+    usage?: Array<UsageIngestParams.Usage>;
+}
 export declare namespace UsageIngestParams {
     interface Usage {
         customer_id: string;
@@ -320,6 +485,6 @@ export interface UsageSearchParams {
     transactionIds: Array<string>;
 }
 export declare namespace Usage {
-    export { type UsageListResponse as UsageListResponse, type UsageListWithGroupsResponse as UsageListWithGroupsResponse, type UsageSearchResponse as UsageSearchResponse, UsageListWithGroupsResponsesCursorPage as UsageListWithGroupsResponsesCursorPage, type UsageListParams as UsageListParams, type UsageIngestParams as UsageIngestParams, type UsageListWithGroupsParams as UsageListWithGroupsParams, type UsageSearchParams as UsageSearchParams, };
+    export { type UsageListResponse as UsageListResponse, type UsageListWithGroupsResponse as UsageListWithGroupsResponse, type UsageSearchResponse as UsageSearchResponse, type UsageListResponsesCursorPageWithoutLimit as UsageListResponsesCursorPageWithoutLimit, type UsageListWithGroupsResponsesCursorPage as UsageListWithGroupsResponsesCursorPage, type UsageListParams as UsageListParams, type UsageIngestParams as UsageIngestParams, type UsageListWithGroupsParams as UsageListWithGroupsParams, type UsageSearchParams as UsageSearchParams, };
 }
 //# sourceMappingURL=usage.d.ts.map

package/resources/v1/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/resources/v1/usage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/resources/v1/usage.ts"],"names":[],"mappings":"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"}

package/resources/v1/usage.js

@@ -1,41 +1,203 @@
 "use strict";
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UsageListWithGroupsResponsesCursorPage = exports.Usage = void 0;
-const resource_1 = require("../../resource.js");
-const core_1 = require("../../core.js");
-const pagination_1 = require("../../pagination.js");
+exports.Usage = void 0;
+const resource_1 = require("../../core/resource.js");
+const pagination_1 = require("../../core/pagination.js");
+const headers_1 = require("../../internal/headers.js");
 class Usage extends resource_1.APIResource {
     /**
-     * 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
      *
      * @example
      * ```ts
-     * const usages = await client.v1.usage.list({
+     * // Automatically fetches more pages as needed.
+     * for await (const usageListResponse of client.v1.usage.list({
      *   ending_before: '2021-01-03T00:00:00Z',
      *   starting_on: '2021-01-01T00:00:00Z',
      *   window_size: 'day',
-     * });
+     * })) {
+     *   // ...
+     * }
      * ```
      */
     list(params, options) {
         const { next_page, ...body } = params;
-        return this._client.post('/v1/usage', { query: { next_page }, body, ...options });
+        return this._client.getAPIList('/v1/usage', (pagination_1.CursorPageWithoutLimit), {
+            query: { next_page },
+            body,
+            method: 'post',
+            ...options,
+        });
     }
-    ingest(body, options) {
-        if ((0, core_1.isRequestOptions)(body)) {
-            return this.ingest(undefined, body);
-        }
+    /**
+     * 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 the [Send usage events](/guides/events/send-usage-events) guide 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"
+     *   }
+     * }
+     * ```
+     *
+     * Learn more about
+     * [usage event structure definitions](/guides/events/design-usage-events).
+     *
+     * #### 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.
+     *
+     * @example
+     * ```ts
+     * await client.v1.usage.ingest();
+     * ```
+     */
+    ingest(params = undefined, options) {
+        const { usage } = params ?? {};
         return this._client.post('/v1/ingest', {
-            body,
+            body: usage,
             ...options,
-            headers: { Accept: '*/*', ...options?.headers },
+            headers: (0, headers_1.buildHeaders)([{ Accept: '*/*' }, options?.headers]),
         });
     }
     /**
-     * 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
      *
      * @example
      * ```ts
@@ -60,7 +222,7 @@ class Usage extends resource_1.APIResource {
      */
     listWithGroups(params, options) {
         const { limit, next_page, ...body } = params;
-        return this._client.getAPIList('/v1/usage/groups', UsageListWithGroupsResponsesCursorPage, {
+        return this._client.getAPIList('/v1/usage/groups', (pagination_1.CursorPage), {
             query: { limit, next_page },
             body,
             method: 'post',
@@ -68,10 +230,40 @@ class Usage extends resource_1.APIResource {
         });
     }
     /**
-     * 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.
      *
      * @example
      * ```ts
@@ -85,8 +277,4 @@ class Usage extends resource_1.APIResource {
     }
 }
 exports.Usage = Usage;
-class UsageListWithGroupsResponsesCursorPage extends pagination_1.CursorPage {
-}
-exports.UsageListWithGroupsResponsesCursorPage = UsageListWithGroupsResponsesCursorPage;
-Usage.UsageListWithGroupsResponsesCursorPage = UsageListWithGroupsResponsesCursorPage;
 //# sourceMappingURL=usage.js.map