GET /v1/projects/:projectId/conversions

GET/v1/projects/:projectId/conversions

Phase 1stable

Auth: Bearer
Scope: events:read

Aggregates conversion events over a time window. Use it to render conversion widgets without walking the raw event stream and re-bucketing client-side.

Totals count every event matching the filter in the window. groups is present when groupBy is set — buckets are sparse, so zero-volume groups are omitted. value sums only events that carry a numeric value property; currency mixing is not normalized — pass a single-currency filter if you need a clean sum.

Path

projectId
stringrequired
Project ID.

Query

since
string (ISO-8601)required
Inclusive lower bound on `occurred_at`.
until
string (ISO-8601)required
Exclusive upper bound on `occurred_at`.
eventNames
string[]optional
Event names. Comma-separated (`eventNames=a,b`) or repeat the param (`eventNames=a&eventNames=b`). Defaults to the built-in conversion set: `purchase_success`, `subscribe_success`, `trial_start`.
groupBy
string[]optional
Bucketing dimensions. Comma-separated (`groupBy=day,eventName`) or repeat the param (`groupBy=day&groupBy=eventName`).
One of: platform, appId, eventName, day, hour
appId
stringoptional
Filter to a single SDK app.

Example request

curl "https://api.layers.com/v1/projects/prj_01HX9Y7K8M2P4RSTUV56789AB/conversions?since=2026-04-11T00:00:00Z&until=2026-04-18T00:00:00Z&groupBy=day,eventName" \
  -H "Authorization: Bearer lp_live_01HX9Y6K7EJ4T2_4QZpN..."

const { totals, groups } = await layers.conversions.list(
  "prj_01HX9Y7K8M2P4RSTUV56789AB",
  {
    since: "2026-04-11T00:00:00Z",
    until: "2026-04-18T00:00:00Z",
    groupBy: ["day", "eventName"],
  }
);

result = layers.conversions.list(
    project_id="prj_01HX9Y7K8M2P4RSTUV56789AB",
    since="2026-04-11T00:00:00Z",
    until="2026-04-18T00:00:00Z",
    group_by=["day", "eventName"],
)

Response

200OK

{
  "window": {
    "since": "2026-04-11T00:00:00Z",
    "until": "2026-04-18T00:00:00Z"
  },
  "totals": {
    "count": 1284,
    "uniqueUsers": 912,
    "value": 22647.4,
    "currency": "USD"
  },
  "groups": [
    {
      "key": { "day": "2026-04-11", "eventName": "purchase_success" },
      "count": 142,
      "uniqueUsers": 131,
      "value": 2501.85
    },
    {
      "key": { "day": "2026-04-11", "eventName": "subscribe_success" },
      "count": 38,
      "uniqueUsers": 38,
      "value": 380.00
    },
    {
      "key": { "day": "2026-04-12", "eventName": "purchase_success" },
      "count": 201,
      "uniqueUsers": 185,
      "value": 3487.20
    }
  ]
}

Errors

Status	Code	When
422	`VALIDATION`	Missing or malformed `since`/`until`, unknown `groupBy` dimension, window > 92 days.
401	`UNAUTHENTICATED`	Missing or invalid key.
403	`FORBIDDEN_SCOPE`	Key lacks `events:read`.
404	`NOT_FOUND`	Project does not exist.
429	`RATE_LIMITED`	Read budget exhausted.

GET /v1/projects/:projectId/conversions

Example request

Response

Errors

See also

On this page