Create a metric

Creates an event-backed metric. Pass the query as the DSL string (query) or the typed IR (query_ir) — exactly one. event_name must equal the event the query…

Creates an event-backed metric. Pass the query as the DSL string (query) or the typed IR (query_ir) — exactly one. event_name must equal the event the query references.

Returns 409 if a metric with the same name already exists, and 422 if the query is invalid or references an unregistered event / label.

Use cases

Track an event — count_users(<event>) for unique-user counts.
Sum a value — sum(<event>, <label>) for revenue / quantity metrics.
Experiment success metric — create the metric, then attach its id to an experiment.

Authorization

bearerSdkKey

AuthorizationBearer <token>

Pass an admin SDK key as Authorization: Bearer sdk_admin_…. Mint via POST /api/admin/keys with type: "admin".

In: header

Project the request operates on. Optional — defaults to the project the SDK key belongs to; pass it only to scope a multi-project key (the generated client sets it once from its configuration, so per-call callers never thread it).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*MetricName

Stable metric key. Single segment or folder.name; lowercase letters, digits, _/-; max 128 chars.

Match^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$

Lengthlength <= 128

folder?|

Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).

event_name*MetricEventName

Source event the query reads from.

Length1 <= length

query*MetricQueryDsl

Metric query DSL string, e.g. sum(purchase, amount). The alternative to query_ir. Every label the query references — in filters, the value position, by (…), or without (…) — must exist as a property on the tracked event's payload; a query over a label the event never carries validates fine but returns empty results.

Length1 <= length <= 4096

winsorize_pct?MetricWinsorizePct

Winsorise percentile (1–99) to clamp outliers. Defaults to 99.

Default99

Range1 <= value <= 99

default_min_effect_of_interest?|

Default minimum effect of interest (relative, 0–1) — the smallest change in this metric worth acting on, used as the power-planning baseline. Intrinsic to the metric; an experiment overrides it per-attachment with min_effect_of_interest when a specific decision has a different cost/risk bar. null to omit.

Defaultnull

direction?MetricDirection

Desired direction of movement. higher_better (default), lower_better, or neutral (guardrail).

Default"higher_better"

Value in"higher_better" | "lower_better" | "neutral"

name*MetricName

Stable metric key. Single segment or folder.name; lowercase letters, digits, _/-; max 128 chars.

Match^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$

Lengthlength <= 128

folder?|

Optional folder name grouping items in the dashboard. Alphanumeric, _ or - (no /). Part of the SDK lookup key (<folder>/<name>).

event_name*MetricEventName

Source event the query reads from.

Length1 <= length

query_ir*

Typed query IR — the structured alternative to the query DSL string. Exactly one of query / query_ir is supplied per metric body.

winsorize_pct?MetricWinsorizePct

Winsorise percentile (1–99) to clamp outliers. Defaults to 99.

Default99

Range1 <= value <= 99

default_min_effect_of_interest?|

Defaultnull

direction?MetricDirection

Desired direction of movement. higher_better (default), lower_better, or neutral (guardrail).

Default"higher_better"

Value in"higher_better" | "lower_better" | "neutral"

Response Body

`application/json`

curl -X POST "https://shipeasy.ai/api/admin/metrics" \  -H "Content-Type: application/json" \  -d '{    "name": "checkouts",    "event_name": "checkout_completed",    "query": "count_users(checkout_completed)"  }'

{
  "id": "met_01j7w8a1b2c3d4e5f6g7h8i9j0",
  "name": "checkouts"
}

{
  "error": "Malformed request (bad JSON, missing project scope).",
  "code": "BAD_REQUEST"
}

{
  "error": "Missing or invalid admin SDK key.",
  "code": "UNAUTHORIZED"
}

{
  "error": "Key is valid but not allowed to act on this project.",
  "code": "FORBIDDEN"
}

{
  "error": "The resource does not exist or is not visible to the caller.",
  "code": "NOT_FOUND"
}

{
  "error": "A resource with this name already exists in the project.",
  "code": "ALREADY_EXISTS"
}

{
  "error": "The request body failed structural (schema) validation.",
  "code": "VALIDATION"
}

Was this page helpful?

✎ Edit this page

Create a metric

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

Not an admin of this project

Feature gated behind a higher plan

Duplicate name

Still referenced by another resource

Illegal lifecycle transition

Edited an immutable field while running

Schema validation failed

Referenced entity missing

Group weights must sum to 10000

Event still pending review

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`