---
title: "Read Events"
method: POST
path: "/api/events/filter"
tags: ["Events"]
---

# Read Events

`POST /api/events/filter`

Queries for Events matching the given filter criteria in the given Account.  Returns
the first page of results, and the URL to request the next page (if there are more
results).

## Headers

- `x-prefect-api-version` string

## Request body

- BodyReadEventsEventsFilterPost
  - `filter` EventFilter — A base class for filtering event data.
    - `occurred` EventOccurredFilter — A base class for filtering event data.
      - `since` string, date-time — Only include events after this time (inclusive)
      - `until` string, date-time — Only include events prior to this time (inclusive)
    - `event` EventNameFilter — A base class for filtering event data.
      - `prefix` string[] — Only include events matching one of these prefixes
      - `exclude_prefix` string[] — Exclude events matching one of these prefixes
      - `name` string[] — Only include events matching one of these names exactly
      - `exclude_name` string[] — Exclude events matching one of these names exactly
    - `any_resource` EventAnyResourceFilter — A base class for filtering event data.
      - `id` string[] — Only include events for resources with these IDs
      - `id_prefix` string[] — Only include events for resources with IDs starting with these prefixes
      - `labels` ResourceSpecification — A specification that may match zero, one, or many resources, used to target or select a set of resources in a query or automation. A resource must match at least one value of all of the provided labels
    - `resource` EventResourceFilter — A base class for filtering event data.
      - `id` string[] — Only include events for resources with these IDs
      - `id_prefix` string[] — Only include events for resources with IDs starting with these prefixes.
      - `labels` ResourceSpecification — A specification that may match zero, one, or many resources, used to target or select a set of resources in a query or automation. A resource must match at least one value of all of the provided labels
      - `distinct` boolean — Only include events for distinct resources
    - `related` EventRelatedFilter — A base class for filtering event data.
      - `id` string[] — Only include events for related resources with these IDs
      - `role` string[] — Only include events for related resources in these roles
      - `resources_in_roles` array[] — Only include events with specific related resources in specific roles
        - unknown[]
          - unknown
      - `labels` ResourceSpecification — A specification that may match zero, one, or many resources, used to target or select a set of resources in a query or automation. A resource must match at least one value of all of the provided labels
    - `id` EventIDFilter — A base class for filtering event data.
      - `id` string[] — Only include events with one of these IDs
    - `order` 'ASC' | 'DESC' — An enumeration.
  - `limit` integer — The number of events to return with each page

## Response `200`

Successful Response

- EventPage — A single page of events returned from the API, with an optional link to the next page of results
  - `events` ReceivedEvent[], required — The Events matching the query
    - `occurred` string, date-time, required — When the event happened from the sender's perspective
    - `event` string, required — The name of the event that happened
    - `resource` Resource, required — An observable business object of interest to the user
    - `related` RelatedResource[] — A list of additional Resources involved in this event
    - `payload` object — An open-ended set of data describing what happened
    - `id` string, uuid, required — The client-provided identifier of this event
    - `follows` string, uuid — The ID of an event that is known to have occurred prior to this one. If set, this may be used to establish a more precise ordering of causally-related events when they occur close enough together in time that the system may receive them out-of-order.
    - `received` string, date-time — When the event was received by Prefect Cloud
  - `total` integer, required — The total number of matching Events
  - `next_page` string, uri, required — The URL for the next page of results, if there are more

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/prefecthq/apis/untitled-api.md) · [All operations](https://skmtc.dev/prefecthq/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/prefecthq/untitled-api/revisions/a7958ce57e96/schema)