> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Query usage events ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json get /events openapi: 3.0.1 info: title: Usage Based Billing API version: 1.0.0 description: An Orchestrator for Usage Based Billing and Payments servers: - url: https://api-m.sandbox.paypal.com/v1/commerce/billing security: - BearerAuth: - read - write tags: - name: Alerts description: API endpoints for managing subscription alerts - name: Events description: API endpoints for managing events - name: Metrics description: API endpoints for metrics and usage data - name: Merchant Activation description: API endpoint for merchant activation - name: Credit Notes description: API endpoints for credit notes management - name: Customers description: API endpoints for customer management - name: Invoices description: API endpoints for invoice management - name: Plans description: API endpoints for subscription plans - name: Subscriptions description: API endpoints for subscriptions - name: Wallets description: API endpoints for wallet management - name: Taxes description: API endpoints for tax management - name: Billing Entities description: API endpoints for billing entities - name: Features description: API endpoints for managing features and privileges - name: Entitlements description: API endpoints for managing plan and subscription entitlements paths: /events: get: tags: - Events summary: Query usage events operationId: GetEvents parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/per_page' - in: query name: external_subscription_id schema: type: string example: sub_1234567890abcdef description: Filter events by external subscription ID - in: query name: metric_code schema: type: string example: metric_123456ef description: Filter events by metric code - in: query name: from_date schema: type: string format: date-time example: '2023-01-01T00:00:00Z' description: Start date for filtering events - in: query name: to_date schema: type: string format: date-time example: '2023-01-01T00:00:00Z' description: End date for filtering events responses: '200': description: A list of usage events content: application/json: schema: type: object properties: events: type: array items: $ref: '#/components/schemas/EventResponse' metadata: $ref: '#/components/schemas/PaginationMetadata' example: events: - transaction_id: event_1752016113 external_subscription_id: 49fac470-fa34-4471-915e-bff1d05308ce metric_code: EvolvAI_Billable_Metrics_1750804981 timestamp: '2025-01-01T00:00:00Z' properties: gb: 12 id: 87b5897d-083f-490c-b5f5-d219087b4d73 created_at: '2025-07-08T16:08:33-07:00' - transaction_id: event_1752016329 external_subscription_id: b40f7d03-cf36-4cb6-b7af-bb3468f91072 metric_code: EvolvAI_Billable_Metrics_1751495485 timestamp: '2025-01-02T00:00:00Z' properties: gb: 12 id: 42365b30-368a-4a0e-be4f-b790dab2cde9 created_at: '2025-01-02T00:00:00Z' - transaction_id: event_1752016319 external_subscription_id: b40f7d03-cf36-4cb6-b7af-bb3468f91072 metric_code: EvolvAI_Billable_Metrics_1751495485 timestamp: '2025-01-01T00:00:00Z' properties: gb: 12 id: 38d78dd1-219e-43bb-af97-7e888e952605 created_at: '2025-01-02T00:00:00Z' - transaction_id: event_1752016316 external_subscription_id: b40f7d03-cf36-4cb6-b7af-bb3468f910721 metric_code: EvolvAI_Billable_Metrics_1751495485 timestamp: '2025-01-01T00:00:00Z' properties: gb: 12 id: 2ee6fbfc-132c-4628-9138-450b27d68b32 created_at: '2025-01-02T00:00:00Z' - transaction_id: event_1752016310 external_subscription_id: b40f7d03-cf36-4cb6-b7af-bb3468f91072 metric_code: EvolvAI_Billable_Metrics_17514954851 timestamp: '2025-01-01T00:00:00Z' properties: gb: 12 id: 67505fef-8dae-4547-b595-5f4265ac6a82 created_at: '2025-01-02T00:00:00Z' - transaction_id: event_1752016198 external_subscription_id: b40f7d03-cf36-4cb6-b7af-bb3468f91072 metric_code: EvolvAI_Billable_Metrics_1751495485 timestamp: '2025-01-01T00:00:00Z' properties: gb: 12 id: 7f4d2d59-4691-4372-9931-aabef31a1cec created_at: '2025-01-02T00:00:00Z' - transaction_id: event_1752016186 external_subscription_id: b40f7d03-cf36-4cb6-b7af-bb3468f91072 metric_code: EvolvAI_Billable_Metrics_1751495485 timestamp: '2025-01-01T00:00:00Z' properties: gb: 12 id: aa237cc9-e975-4486-a5cf-f2c0999190a9 created_at: '2025-01-02T00:00:00Z' - transaction_id: event_1752016165 external_subscription_id: b40f7d03-cf36-4cb6-b7af-bb3468f91072 metric_code: EvolvAI_Billable_Metrics_1751495485 timestamp: '2025-01-06T00:00:00Z' properties: gb: 12 id: 528be51f-ee55-4c14-8306-50a26638190f created_at: '2025-01-06T00:00:00Z' - transaction_id: event_1752016139 external_subscription_id: b40f7d03-cf36-4cb6-b7af-bb3468f91072 metric_code: EvolvAI_Billable_Metrics_1751495485 timestamp: '2025-01-01T00:00:00Z' properties: gb: 12 id: fe027df2-078f-4a92-9335-1c0f1c0d4123 created_at: '2025-01-05T00:00:00Z' - transaction_id: event_1752016138 external_subscription_id: b40f7d03-cf36-4cb6-b7af-bb3468f91072 metric_code: EvolvAI_Billable_Metrics_1751495485 timestamp: '2025-01-04T00:00:00Z' properties: gb: 12 id: 91b72931-6c5e-48e4-8156-27621857c9c5 created_at: '2025-01-03T00:00:00Z' metadata: current_page: 1 total_pages: 4 total_count: 32 '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: parameters: page: name: page in: query description: Page number schema: type: integer per_page: name: per_page in: query description: Number of records per page schema: type: integer schemas: EventResponse: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: id: type: string description: Unique identifier for the event example: evt_1234567890abcdef created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' description: Timestamp when the event was created example: '2023-01-01T00:00:00Z' PaginationMetadata: type: object properties: total_count: type: integer total_pages: type: integer current_page: type: integer EventBase: type: object properties: transaction_id: type: string description: Unique identifier for the transaction associated with the event example: txn_1234567890abcdef external_subscription_id: type: string description: External subscription ID associated with the event example: sub_1234567890abcdef metric_code: type: string description: >- Identifier for the targeted metric. This value must match the `code` property of an active metric; otherwise, it will be disregarded during processing. example: event_code_123456 timestamp: allOf: - $ref: '#/components/schemas/DateTimeWithZone' description: Timestamp when the event occurred example: '2023-01-01T00:00:00Z' properties: type: object required: - transaction_id - metric_code - external_subscription_id DateTimeWithZone: type: string format: date-time description: Date and time in ISO 8601 format. example: '2023-10-01T12:00:00Z' Error: type: object properties: name: type: string debug_id: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: type: object properties: field: type: string value: type: string location: type: string issue: type: string description: type: string responses: Forbidden: description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: '#/components/schemas/Error' example: name: NOT_AUTHORIZED message: Authorization failed due to insufficient permissions. debug_id: 565f78f101498 details: - issue: PERMISSION_DENIED description: >- You do not have permission to access or perform operations on this resource. NotFound: description: Resource Not Found. content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error - An unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/Error' example: name: INTERNAL_SERVER_ERROR message: An internal server error has occurred. debug_id: 90957fca61718 securitySchemes: BearerAuth: type: oauth2 description: >- Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header. flows: clientCredentials: tokenUrl: https://api-m.sandbox.paypal.com/v1/oauth2/token scopes: read: Read access write: Write access ````