> ## 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.

# Audit usage events

<div className="m-badge-page-wrapper">
  <Badge stroke color="orange" size="sm">Limited Release</Badge>
</div>

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a GET call to the `/v1/commerce/billing/events` endpoint to retrieve usage events recorded with PayPal. Include the following query parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span>                    | Set the page number for paginated results. Default is `1`.                                                                                                                                                                                           |
| `per_page`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span>                | Set the number of events to return per page. Default is `10`, maximum is `100`.                                                                                                                                                                      |
| `external_subscription_id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Set to the `external_id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions" target="_blank" rel="noopener noreferrer">created the subscription</a> to filter events for that subscription. |
| `metric_code`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>              | Set to the `code` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-metrics" target="_blank" rel="noopener noreferrer">created the metric</a> to filter events for that metric.                          |
| `from_date`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                | Set the start date to filter events from this date (ISO 8601 format).                                                                                                                                                                                |
| `to_date`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                  | Set the end date to filter events until this date (ISO 8601 format).                                                                                                                                                                                 |

For information on all parameters, see <a href="/reference/api/rest/events/query-usage-events" target="_blank" rel="noopener noreferrer">API reference</a>.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/events?per_page=10&page=1' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "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
    }
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with the usage events.