---
title: "Search events"
method: POST
path: "/events/search"
tags: ["Event"]
---

# Search events

`POST /events/search`

This endpoint returns a filtered set of events for an account in a [paginated list format](/api-reference/pagination).

Note that this is a `POST` endpoint rather than a `GET` endpoint because it employs a JSON body for search criteria
rather than query parameters, allowing for a more flexible search syntax.

Note that a search criteria _must_ be specified. Currently, Orb supports the following criteria:
- `event_ids`: This is an explicit array of IDs to filter by. Note that an event's ID is the `idempotency_key` that
  was originally used for ingestion.

By default, Orb will not throw a `404` if no events matched, Orb will return an empty array for `data` instead.

## Request body

- EventSearchCriteria
  - `event_ids` string[], required — This is an explicit array of IDs to filter by. Note that an event's ID is the idempotency_key that was originally used for ingestion, and this only supports events that have not been amended. Values in this array will be treated case sensitively.
  - `timeframe_start` string, date-time, nullable — The start of the timeframe, inclusive, in which to search events. If not specified, the one week ago is used.
  - `timeframe_end` string, date-time, nullable — The end of the timeframe, exclusive, in which to search events. If not specified, the current time is used.

## Response `200`

OK

- Events
  - `data` Event[], required
    - `id` string, required — A unique value, generated by the client, that is used to de-duplicate events. Exactly one event with a given idempotency key will be ingested, which allows for safe request retries.
    - `customer_id` string, nullable, required — The Orb Customer identifier
    - `external_customer_id` string, nullable, required — An alias for the Orb customer, whose mapping is specified when creating the customer
    - `event_name` string, required — A name to meaningfully identify the action or event type.
    - `properties` object, required — A dictionary of custom properties. Values in this dictionary must be numeric, boolean, or strings. Nested dictionaries are disallowed.
    - `timestamp` string, date-time, required — An ISO 8601 format date with no timezone offset (i.e. UTC). This should represent the time that usage was recorded, and is particularly important to attribute usage to a given billing period.
    - `deprecated` boolean, required — A boolean indicating whether the event is currently deprecated.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

---

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