Success metrics#

Manage the GA4 events an organization tracks as success metrics for reporting.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/success-metrics#

List the organization's selected success metrics: the GA4 events it defines as success (e.g. sign-ups, purchases).

bash

GET /v1/success-metrics?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

POST /v1/success-metrics#

Add success metrics, or replace the current selection during GA4 setup. Historical event data is backfilled automatically.

Owner only

bash

POST /v1/success-metrics
Authorization: Bearer {token}
Content-Type: application/json

{
  "organization_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "metrics": "..."
}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
replaceExisting	`boolean`	—	When true, remove success metrics not included in this request before saving the selected metrics.
metrics	`Array<object>`	Required	Success metrics to add. An empty array clears all metrics when replaceExisting is true; otherwise it is a no-op.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

DELETE /v1/success-metrics/:id#

Remove a success metric and purge its synced event data.

Owner only

bash

DELETE /v1/success-metrics/:id
Authorization: Bearer {token}
Content-Type: application/json

{
  "organization_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "success_metric_id": "..."
}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
successMetricId	`string (UUID)`	Required	Success metric identifier to remove.

Response#

Returns { data, _meta } with the result.

PUT /v1/success-metrics/:id/dimensions#

Update the registered GA4 custom dimensions tracked for one success event and backfill their aggregate values.

Owner only

bash

PUT /v1/success-metrics/:id/dimensions
Authorization: Bearer {token}
Content-Type: application/json

{
  "organization_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "success_metric_id": "...",
  "dimensions": "..."
}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
successMetricId	`string (UUID)`	Required	Success metric whose custom dimensions are replaced.
dimensions	`Array<object>`	Required	Desired registered event-scoped GA4 custom dimensions for this success metric.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.