> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Events

> Get a list of all events.



## OpenAPI

````yaml get /events
openapi: 3.1.0
info:
  title: public
  description: ''
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.102.0
servers:
  - url: https://test.dodopayments.com/
    description: Test Mode Server Host
  - url: https://live.dodopayments.com/
    description: Live Mode Server Host
security: []
tags:
  - name: Products
  - name: Payments
  - name: Subscriptions
  - name: Addons
  - name: Customers
  - name: Refunds
  - name: Disputes
  - name: Events
  - name: License Keys
  - name: Entitlements
  - name: Licenses
  - name: Discounts
  - name: Meters
  - name: Credit Entitlements
  - name: Credit Entitlement Balances
  - name: Outgoing Webhooks
  - name: Checkout
  - name: Webhook Events
paths:
  /events:
    get:
      tags:
        - Events
      summary: Retrieve events with advanced filtering and pagination
      description: >-
        Fetch events from your account with powerful filtering capabilities.
        This endpoint is ideal for:

        - Debugging event ingestion issues

        - Analyzing customer usage patterns

        - Building custom analytics dashboards

        - Auditing billing-related events


        ## Filtering Options:

        - **Customer filtering**: Filter by specific customer ID

        - **Event name filtering**: Filter by event type/name

        - **Meter-based filtering**: Use a meter ID to apply the meter's event
        name and filter criteria automatically

        - **Time range filtering**: Filter events within a specific date range

        - **Pagination**: Navigate through large result sets


        ## Meter Integration:

        When using `meter_id`, the endpoint automatically applies:

        - The meter's configured `event_name` filter

        - The meter's custom filter criteria (if any)

        - If you also provide `event_name`, it must match the meter's event name


        ## Example Queries:

        - Get all events for a customer: `?customer_id=cus_abc123`

        - Get API request events: `?event_name=api_request`

        - Get events from last 24 hours:
        `?start=2024-01-14T10:30:00Z&end=2024-01-15T10:30:00Z`

        - Get events with meter filtering: `?meter_id=mtr_xyz789`

        - Paginate results: `?page_size=50&page_number=2`
      operationId: get_events
      parameters:
        - name: customer_id
          in: query
          description: Filter events by customer ID
          required: false
          schema:
            type: string
          style: form
        - name: event_name
          in: query
          description: >-
            Filter events by event name. If both event_name and meter_id are
            provided, they must match the meter's configured event_name
          required: false
          schema:
            type: string
          style: form
        - name: meter_id
          in: query
          description: >-
            Filter events by meter ID. When provided, only events that match the
            meter's event_name and filter criteria will be returned
          required: false
          schema:
            type: string
          style: form
        - name: page_size
          in: query
          description: 'Number of events to return per page (default: 10)'
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
          style: form
        - name: page_number
          in: query
          description: 'Page number (0-based, default: 0)'
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
          style: form
        - name: start
          in: query
          description: Filter events created after this timestamp
          required: false
          schema:
            type: string
            format: date-time
          style: form
        - name: end
          in: query
          description: Filter events created before this timestamp
          required: false
          schema:
            type: string
            format: date-time
          style: form
      responses:
        '200':
          description: Events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEventsResponse'
        '400':
          description: >-
            Invalid request - invalid query parameters, conflicting meter/event
            names, or malformed dates
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Meter not found - the specified meter_id does not exist
        '422':
          description: Unprocessable entity - validation errors in query parameters
      security:
        - API_KEY: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import DodoPayments from 'dodopayments';

            const client = new DodoPayments({
              bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
            });

            // Automatically fetches more pages as needed.
            for await (const event of client.usageEvents.list()) {
              console.log(event.business_id);
            }
        - lang: Python
          source: |-
            import os
            from dodopayments import DodoPayments

            client = DodoPayments(
                bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
            )
            page = client.usage_events.list()
            page = page.items[0]
            print(page.business_id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/dodopayments/dodopayments-go\"\n\t\"github.com/dodopayments/dodopayments-go/option\"\n)\n\nfunc main() {\n\tclient := dodopayments.NewClient(\n\t\toption.WithBearerToken(\"My Bearer Token\"),\n\t)\n\tpage, err := client.UsageEvents.List(context.TODO(), dodopayments.UsageEventListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
        - lang: Java
          source: |-
            package com.dodopayments.api.example;

            import com.dodopayments.api.client.DodoPaymentsClient;
            import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
            import com.dodopayments.api.models.usageevents.UsageEventListPage;
            import com.dodopayments.api.models.usageevents.UsageEventListParams;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();

                    UsageEventListPage page = client.usageEvents().list();
                }
            }
        - lang: Kotlin
          source: |-
            package com.dodopayments.api.example

            import com.dodopayments.api.client.DodoPaymentsClient
            import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient
            import com.dodopayments.api.models.usageevents.UsageEventListPage
            import com.dodopayments.api.models.usageevents.UsageEventListParams

            fun main() {
                val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

                val page: UsageEventListPage = client.usageEvents().list()
            }
        - lang: Ruby
          source: |-
            require "dodopayments"

            dodo_payments = Dodopayments::Client.new(
              bearer_token: "My Bearer Token",
              environment: "test_mode" # defaults to "live_mode"
            )

            page = dodo_payments.usage_events.list

            puts(page)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Dodopayments\Client;
            use Dodopayments\Core\Exceptions\APIException;

            $client = new Client(
              bearerToken: getenv('DODO_PAYMENTS_API_KEY') ?: 'My Bearer Token',
              environment: 'test_mode',
            );

            try {
              $page = $client->usageEvents->list(
                customerID: 'customer_id',
                end: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'),
                eventName: 'event_name',
                meterID: 'meter_id',
                pageNumber: 0,
                pageSize: 0,
                start: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'),
              );

              var_dump($page);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: |-
            using System;
            using DodoPayments.Client;
            using DodoPayments.Client.Models.UsageEvents;

            DodoPaymentsClient client = new();

            UsageEventListParams parameters = new();

            var page = await client.UsageEvents.List(parameters);
            await foreach (var item in page.Paginate())
            {
                Console.WriteLine(item);
            }
components:
  schemas:
    GetEventsResponse:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    Event:
      type: object
      required:
        - event_id
        - business_id
        - customer_id
        - event_name
        - timestamp
      properties:
        business_id:
          type: string
        customer_id:
          type: string
        event_id:
          type: string
        event_name:
          type: string
        metadata:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/EventMetadata'
        timestamp:
          type: string
          format: date-time
    EventMetadata:
      type: object
      title: EventMetadata
      description: >-
        Arbitrary key-value metadata. Values can be string, integer, number, or
        boolean.
      additionalProperties:
        oneOf:
          - type: string
            title: String
          - type: integer
            title: Integer
            format: int64
          - type: number
            title: Number
            format: double
          - type: boolean
            title: Boolean
        title: Event Metadata Value
        description: Metadata value can be a string, integer, number, or boolean
  securitySchemes:
    API_KEY:
      type: http
      scheme: bearer

````