Skip to main content
POST
Create a new event

Authorizations

Authorization
string
header
required

Send Authorization: Bearer <credential> using either a Clerk session JWT or a Clerk API key (ak_*). API keys may identify a user (user_*) or organization (org_*) principal and are generated in the Clerk Dashboard under API keys.

Body

application/json
metadata
object
required
name
string
required
Minimum string length: 5
date
string<date-time> | null
required
description
string
required
tags
object[]
required
category
enum<string>
required
Available options:
BUSINESS,
TECHNICAL,
PROVIDER
labels
string[]
required
widgetEvents
object[]
required

Chart annotation associated with the event. Send an empty array for an event without a chart, or one item containing its grid layout, title, description, and Advanced Explorer request. POST /events accepts at most one item.

Maximum array length: 1
id
string
metricId
string

Legacy event-level metric context. Usually omit it: when a chart is provided in widgetEvents, the backend derives this from its first cost query.

groupBy
string

Legacy event-level group-by dimension. Usually omit it: when a chart is provided in widgetEvents, the backend derives this from its first cost query.

datePreset
enum<string>

Legacy event-level chart period preset. Usually omit it: the backend derives the period from widgetEvents.

Available options:
TRAILING_90_DAYS,
TRAILING_30_DAYS,
TRAILING_45_DAYS,
TRAILING_7_DAYS,
TRAILING_3_DAYS,
TRAILING_14_WEEKS,
MTD,
QTD,
YTD,
LAST_WEEK,
LAST_MONTH,
LAST_6_MONTHS,
LAST_12_MONTHS,
LAST_4_YEARS,
LAST_3_MONTHS,
LAST_INVOICE_MONTH
startDate
string

Legacy event-level custom period start date. Usually omit it: the backend derives the period from widgetEvents.

endDate
string

Legacy event-level custom period end date. Usually omit it: the backend derives the period from widgetEvents.

conditions
object | null

Legacy event-level query-builder filter. Usually omit it: the backend derives conditions from the first cost query's whereClause in widgetEvents.

currency
enum<string>
default:USD

Legacy event-level chart currency. Usually omit it: the backend derives currency from widgetEvents.

Available options:
EUR,
USD,
GBP,
CNY
createdBy
object | null

Response

Event created successfully

The response is of type string.

Last modified on July 24, 2026