--- updatedAt: 2026-07-09T23:15:17.000Z agentTools: projectIndex: https://docs.pelcro.com/llms.txt --- # Conversion Rate by Dimension Conversions and conversion rate for an event, grouped by a dimension. For each value of the chosen `dimension`, returns the number of conversion events (`conversions`, numerator), the number of base events (`base`, denominator — defaults to **Page Viewed**), and `conversion_rate` = conversions / base × 100. * `conversion_rate` is **null** when a bucket has zero base events. * A rate can exceed 100% when a bucket records more conversions than base events. * Results are ordered by `conversions`, highest first. * Pass `user_id` to scope to a single customer belonging to the site. Use it for "which country/platform/channel converts best?" # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "core-api", "version": "1.88" }, "servers": [ { "url": "https://www.pelcro.com/api/v1/core" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "in": "header", "name": "Authorization", "x-bearer-format": "bearer" }, "sec1": { "type": "apiKey", "in": "query", "name": "site_id" } } }, "security": [ { "sec0": [], "sec1": [] } ], "paths": { "/analytics/customers/activity/conversion-by-dimension": { "get": { "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Dimension buckets, highest conversions first.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The dimension value. Empty referrers are reported as `(direct)`." }, "conversions": { "type": "integer", "description": "Conversion events in this bucket (numerator)." }, "base": { "type": "integer", "description": "Base events in this bucket (denominator)." }, "conversion_rate": { "type": [ "number", "null" ], "description": "conversions / base * 100, or null when base is 0." } } } }, "conversion_event": { "type": "string", "description": "The conversion event (numerator)." }, "base_event": { "type": "string", "description": "The base event (denominator)." }, "dimension": { "type": "string", "description": "The dimension the result was grouped by." }, "user_id": { "type": [ "integer", "null" ], "description": "The customer the result was scoped to, or null for site-wide." }, "days": { "type": "integer", "description": "Size of the resolved window, in days." } } }, "examples": { "Result": { "value": { "data": [ { "label": "US", "conversions": 142, "base": 128400, "conversion_rate": 0.11 }, { "label": "CA", "conversions": 18, "base": 9600, "conversion_rate": 0.19 } ], "conversion_event": "Subscription Created", "base_event": "Page Viewed", "dimension": "country", "user_id": null, "days": 30 } } } } } }, "400": { "description": "Invalid request — a parameter failed validation (unknown event name or dimension, malformed date, out-of-range limit, etc.).", "content": { "application/json": { "examples": { "Result": { "value": { "error": { "status": 400, "message": "Invalid request, please try again." } } } } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "examples": { "Result": { "value": { "error": "Unauthenticated." } } } } } } }, "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "The site ID to scope this request to." }, { "name": "conversion_event", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The conversion event to attribute. Common values: \"Subscription Created\", \"Registered\", \"Newsletter Email Submitted\", \"Invoice Paid\". The valid set is per-site; an unrecognized value returns a 400 listing the events this site has recorded." }, { "name": "base_event", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The base/traffic event used as the denominator. Defaults to \"Page Viewed\". The valid set is per-site; an unrecognized value returns a 400 listing the events this site has recorded." }, { "name": "dimension", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "page", "referrer", "country", "platform", "utm_source", "utm_medium", "utm_campaign" ] }, "description": "The dimension to group by." }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Scope the result to a single customer belonging to the site. Returns 404 if the customer is not on this site." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the window in YYYY-MM-DD. Use with `to`. When omitted, a trailing default window is used. The from–to span is capped at the site’s activity retention window (90 days by default)." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the window in YYYY-MM-DD. Must be on or after `from` and no later than today." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90 }, "description": "Alternative to `from`/`to`: size of the trailing window in days (1–90). Bounded by the site’s activity retention window." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of dimension buckets to return (1–100, default 10)." } ], "operationId": "get_analytics-customers-activity-conversion-by-dimension", "summary": "Conversion Rate by Dimension", "description": "Conversions and conversion rate for an event, grouped by a dimension." } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ``` # Sibling pages * [Count Events](https://docs.pelcro.com/reference/api-core-analytics-customers-activity-count-events.md) * [Top Pages](https://docs.pelcro.com/reference/api-core-analytics-customers-activity-top-pages.md) * [Top Referrers](https://docs.pelcro.com/reference/api-core-analytics-customers-activity-top-referrers.md) * [Customer Journey](https://docs.pelcro.com/reference/api-core-analytics-customers-activity-journey.md)