API reference

Metric definitions

Define, list and delete the metrics kept on every profile.

A metric definition (also called a claim) tells BreezeIQ which value to keep on each profile from one event type. See Metrics for value kinds and examples.

Create a metric definition#

PUT /v1/tenants/{tenant}/metric-definitions Tenant token

Creates a claim. Create-only: returns 409 if this (metric, event) pair already exists.

Body

metric_name string Required

Name shown on profiles and used in segments.

event_name string Required

A registered event type.

value_kind string Required

count, property_number, occurred_at_epoch or property_string. See Metrics.

value_path string

Required for property_number and property_string, such as "properties.amount".

aggregation string

property_string only, and required there: "latest" or "recent".

keep number

recent only: list length, 1–10. Default 5.

window_days number

1–730, for count and property_number: a rolling window.

workspace_id string

"*" (default) for every workspace, or one workspace id.

display_name string

Label.

description string

Label.

bash

curl -X PUT "https://api.breeze.in/cdp/control-plane/v1/tenants/breeze/metric-definitions" \
  -H "Authorization: Bearer $BREEZEIQ_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "metric_name": "spend_last_30d",
    "event_name": "purchase",
    "value_kind": "property_number",
    "value_path": "properties.amount",
    "window_days": 30,
    "display_name": "Spend (30 days)"
  }'

json

{
  "tenant_id": "breeze",
  "metric_name": "spend_last_30d",
  "status": "created"
}

Takes effect within about a minute. Invalid combinations return 422 with the reason, for example "aggregation 'latest' takes no keep".

List metric definitions#

GET /v1/tenants/{tenant}/metric-definitions Workspace token

bash

curl "https://api.breeze.in/cdp/control-plane/v1/tenants/breeze/metric-definitions" \
  -H "Authorization: Bearer $BREEZEIQ_TOKEN"

json

{
  "metric_definitions": [
    {
      "workspace_id": "*",
      "metric_name": "total_spend",
      "event_name": "purchase",
      "value_kind": "property_number",
      "value_path": "properties.amount",
      "display_name": "Total spend",
      "description": null,
      "window_days": null,
      "aggregation": null,
      "keep": null
    },
    {
      "workspace_id": "*",
      "metric_name": "recent_cart_adds",
      "event_name": "addtocart",
      "value_kind": "property_string",
      "value_path": "properties.product_id",
      "display_name": "Recent cart adds",
      "description": null,
      "window_days": null,
      "aggregation": "recent",
      "keep": 5
    }
  ]
}

Delete a metric definition#

DELETE /v1/tenants/{tenant}/metric-definitions Tenant token

Stops collecting a claim. Values already computed keep their last value.

Query

metric_name string

The metric to stop.

event_name string

The event type it reads from.

workspace_id string

Defaults to *.

bash

curl -X DELETE "https://api.breeze.in/cdp/control-plane/v1/tenants/breeze/metric-definitions?metric_name=spend_last_30d&event_name=purchase" \
  -H "Authorization: Bearer $BREEZEIQ_TOKEN"