Define a conversion goal
A goal is a named rule over analytics events. Edge evaluates the rule at query time, so a new goal can report on events already inside the retention window.
Goal creation is not available in the web console. Use an agent, the CLI, or the API. The resulting conversion appears in the console's Analytics → Conversions → Goals view.
1. Choose what counts
Goal types are pageview, custom_event, outbound_link, file_download, form_submission and not_found.
The distribution's type limits what can fire:
siteandpagesupport every goal type.embed_scriptandembed_iframesupport custom events and form submissions; link, download and not-found goals are available but are not suggested by default.datasupports no goals.
Edge rejects an incompatible definition instead of creating a goal that can never convert.
2. Check the rule against existing events
This example counts visits to /thanks as a conversion.
Check how a pageview goal for the exact path /thanks would have performed
on acme-marketing over the last 28 days. Exclude bots.edge api POST /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/goals/check --input - <<'EOF'
{
"goal_type": "pageview",
"predicate": {
"path": { "op": "eq", "value": "/thanks" }
},
"source_constraint": "any",
"range": { "preset": "last_28_days" },
"include_bots": false
}
EOFcurl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/goals/check \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"goal_type": "pageview",
"predicate": {
"path": { "op": "eq", "value": "/thanks" }
},
"source_constraint": "any",
"range": { "preset": "last_28_days" },
"include_bots": false
}'The agent runs edge_goal_check. The result includes total and unique conversions, conversion rate and a small sample of matching events. Checking does not save anything.
Path rules support eq, prefix and matches. In a matches rule, * matches one path segment and ** matches any remaining segments.
3. Save the goal
Create a goal on acme-marketing named "Reached thank-you page", with the
slug reached-thanks, using the pageview rule we just checked.edge api POST /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/goals --input - <<'EOF'
{
"slug": "reached-thanks",
"display_name": "Reached thank-you page",
"description": "A visitor reached the post-signup thank-you page.",
"goal_type": "pageview",
"predicate": {
"path": { "op": "eq", "value": "/thanks" }
},
"source_constraint": "any"
}
EOFcurl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/goals \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "reached-thanks",
"display_name": "Reached thank-you page",
"description": "A visitor reached the post-signup thank-you page.",
"goal_type": "pageview",
"predicate": {
"path": { "op": "eq", "value": "/thanks" }
},
"source_constraint": "any"
}'The agent runs edge_goal_create. The goal appears in Analytics as soon as the next query loads it; there is no backfill job to wait for.
Event and property rules
A custom_event goal requires an exact event_name. A form_submission goal defaults to server events. source_constraint can be any, client or server where the goal type allows it.
Property clauses use exact equality:
{
"properties": [
{ "key": "plan", "op": "eq", "value": "pro" }
]
}The property must be declared first. This prevents a typo in a property name from silently creating a permanently empty goal.
See Declare an analytics property to promote an observed key.
Changing a goal changes history
Editing a predicate increments its definition_version and re-evaluates retained events under the new rule. Historical conversion numbers can therefore change. Edge records the change and reports when a definition changed inside the queried range.
Archive a goal when it should no longer be used. Archiving preserves its audit history; it does not delete analytics events.