---
title: "Query events metadata"
method: POST
path: "/event-metadata/query"
tags: ["Event Metadata"]
---

# Query events metadata

`POST /event-metadata/query`

## Request

- Base URL: `https://api.omnisend.com/api`
- URL: `https://api.omnisend.com/api/event-metadata/query`
- Auth: one of:
  - API key in header `Authorization`
  - OAuth 2
    - Client credentials
    - Token URL: `https://app.omnisend.com/oauth2/token`

Returns event metadata entries for the given category, optionally filtered
by event names and/or origins.

**Supported categories:** `automations`, `events`, `segments`

**API version scoping:**
The events a category exposes depend on the requested `Omnisend-Version`; a date
between releases resolves to the nearest earlier supported version. Brand-custom
events are not version-scoped.

**Event name filtering:**
When `events` are provided, only events whose system name matches one of the
given values are returned (exact, case-sensitive match).

**Origin filtering:**
By default the response includes Omnisend events together with events from every
origin the brand has data for. When the brand is connected to a specific origin,
that origin's events are included as well. The optional `origins` filter narrows
the response to the requested origins (OR-combined) within what the brand can
already see; an origin the brand is not entitled to is never returned, even if
requested.

**Property inclusion:**
When `includeProperties` is `true`, each event item includes its nested
property tree, keyed by property name, with struct properties nesting their
children under a recursive `properties` map. When omitted or `false`, only
event-level metadata (`name`, `displayName`, `origins`) is returned.

**Custom event exclusion:**
When `excludeCustomEvents` is `true`, brand-custom events are omitted.
When omitted or `false`, custom events are included.
Set this to `true` when only well-known standard events are needed, for a more predictable response size.

**Rate Limiting:**
This endpoint is rate limited to 400 requests per minute.

## Headers

- `Omnisend-Version` string, required

## Request body

- QueryEventsRequest: Request body for the POST /event-metadata/query query endpoint.
  - `category` 'automations' | 'events' | 'segments', required: Event category, resolved against the requested Omnisend-Version
  - `events` string[]: Optional list of event names to filter by
  - `excludeCustomEvents` boolean: When true, brand-custom events are omitted. When false or omitted, custom events are included. Set this to `true` when only well-known events are needed, for a more predictable response size.
  - `includeProperties` boolean: When true, response items include the nested property tree. When false or omitted, only event-level metadata is returned.
  - `origins` string[]: Optional list of origins to filter by (OR-combined)

## Response `200`

List of event metadata entries

- EventsResponse: Root response envelope for all event metadata endpoints.
  - `events` EventItem[]: List of event metadata entries
    - `displayName` string: Human-readable label for the event
    - `explicitlyDefined` boolean: True when the event schema was declared via the write API rather than inferred from the global lexicon or scraped traffic
    - `name` string: Machine-readable event name (e.g. "placed order")
    - `origins` string[]: List of origins that contributed to this event variant
    - `properties` object: Nested tree of properties belonging to this event variant, keyed by property name. Omitted when the request did not set includeProperties=true.

## Other responses

- `400`: Invalid request body, missing or unsupported category
- `401`: Authentication is missing or invalid
- `410`: API version has been retired
- `429`: Rate limit exceeded
- `500`: Unexpected error occurred

---

[API](https://skmtc.dev/omnisend/apis/event-metadata-api.md) - [All operations](https://skmtc.dev/omnisend/apis/event-metadata-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisend/apis/event-metadata-api/revisions/9f74e71142e6?raw)