> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Filter events and notifications by ID, email, or partial value

Search your event and notification logs using any Paddle ID that appears in an event, an email address, or part of one. Filter events by date, too.

---

## What's new?

You can now filter [events](https://developer.paddle.com/api-reference/events/list-events.md) by value and by date, using three new query parameters.

{% api-endpoint method="GET" path="/events" %}

- **filter** (string): Return entities that contain the value specified. Pass a Paddle ID or email address that appears in the event payload, or part of one
- **from** (string): Return entities from a specific time. Pass an RFC 3339 datetime string
- **to** (string): Return entities up to a specific time. Pass an RFC 3339 datetime string
{% /api-endpoint %}

At the same time, the `filter` parameter on [notifications](https://developer.paddle.com/api-reference/notifications/list-notifications.md) matches more criteria than it used to. Previously it only accepted a complete transaction, customer, or subscription ID. It can now filter by the ID of any entity that appears in an event, by email addresses, or by partial values.

## How it works

When something notable occurs in your system, Paddle creates an event entity with information about what happened. You can subscribe to events via webhooks, or you can query the event stream by sending a {% method-badge method="GET" /%} request to the `/events` endpoint.

You can now filter the event stream using new `filter`, `to`, and `from` query parameters. When filtering using the `filter` query parameter, Paddle includes every Paddle ID in an event payload and every email address.

This means you don't need to know which entity an identifier belongs to. Searching for a customer ID returns events for that customer and events for their subscriptions, transactions, and adjustments, because the customer ID appears in all of them.

We also ported this change to the `filter` query parameter that you can use when [listing notifications](https://developer.paddle.com/api-reference/notifications/list-notifications.md), too.

### Matching

How Paddle matches depends on what you pass:

| You pass | Paddle matches |
|---|---|
| A complete Paddle ID or an email address | The exact value |
| The start of a Paddle ID, like `ctm_01h84` | Values that begin with it |
| Anything else | Paddle IDs or email addresses that contain it |

Partial values must be at least three characters. Shorter values return a 400 error. Matching isn't case-sensitive.

### Dates

`from` and `to` take RFC 3339 datetime strings and bound results by when Paddle recorded the event. Both are exclusive, so an event recorded at exactly the time you pass isn't returned.

## Examples

{% accordion %}
{% accordion-item title="Events for a customer" %}

This example returns every event that mentions a customer, including events for their subscriptions and transactions.

{% api-endpoint method="GET" path="/events?filter=ctm_01h8441jn5pcwrfhwh78jqt8hk" %}

- **filter** (string): Return entities that contain the value specified
{% /api-endpoint %}

{% /accordion-item %}
{% accordion-item title="Events for an email address" %}

This example returns events that contain a customer's email address.

{% api-endpoint method="GET" path="/events?filter=ronaldo.zambrano%40example.com" %}

- **filter** (string): Return entities that contain the value specified
{% /api-endpoint %}

{% /accordion-item %}
{% accordion-item title="Events for a date period" %}

This example returns events that Paddle recorded during August 2026.

{% api-endpoint method="GET" path="/events?from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00Z" %}

- **from** (string): Return entities from a specific time. Pass an RFC 3339 datetime string
- **to** (string): Return entities up to a specific time. Pass an RFC 3339 datetime string
{% /api-endpoint %}

{% /accordion-item %}
{% accordion-item title="Combining filters" %}

You can combine the new parameters with `event_type`. This example returns `transaction.completed` events for a subscription in August 2026.

{% api-endpoint method="GET" path="/events?filter=sub_01h04vsc0qhwtsbsxp3rsfsd4p&event_type=transaction.completed&from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00Z" %}

- **filter** (string): Return entities that contain the value specified
- **event_type** (array[string]): Return events that match the specified event type
- **from** (string): Return entities from a specific time. Pass an RFC 3339 datetime string
- **to** (string): Return entities up to a specific time. Pass an RFC 3339 datetime string

{% /api-endpoint %}

{% /accordion-item %}
{% /accordion %}

## Next steps

This change is available in version `1` of the Paddle API.

It's a non-breaking change, meaning it doesn't impact existing integrations. Filters that worked before still return the same results, though when filtering notifications you may now see more results than before.

Paddle retains events for 90 days, so filtering only returns events from that window.

You can [list events](https://developer.paddle.com/api-reference/events/list-events.md) or [list notifications](https://developer.paddle.com/api-reference/notifications/list-notifications.md) using the API to start using the new query parameters.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `filter` | Field | added | List events | Return events that contain a Paddle ID, email address, or partial value. |
| `from` | Field | added | List events | Return events from a specific time. |
| `to` | Field | added | List events | Return events up to a specific time. |
| `filter` | Field | updated | List notifications | Now matches any Paddle ID in an event, email addresses, and partial values. |