Goals
Updated 2026-11-02
What a goal is
A goal is a conversion you care about. It's either a pageview on a path or a custom event.
| Kind | Pattern example | Counts when |
|---|---|---|
path | /thanks | Someone views exactly that path |
path | /welcome/* | Someone views any path under it |
event | signup | Someone triggers a custom event with that exact name |
Only a trailing * works as a wildcard. Event names must match exactly, including case.
Create a goal
Dashboard
Open Goals and fill in the name, what counts, and the page path or event name.
API
curl -X POST https://headstream.app/api/v1/goals \
-H "Authorization: Bearer hsk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"siteId":"SITE_ID","name":"Signups","kind":"event","pattern":"signup"}'
Names can be up to 100 characters, and patterns up to 200. Names must be unique in a project. A duplicate returns 409 with the code conflict.
MCP
Use create_goal, with siteId, name, kind and pattern.
Read results
curl "https://headstream.app/api/v1/goals?siteId=SITE_ID" \
-H "Authorization: Bearer hsk_YOUR_KEY"
Each goal returns:
| Field | Meaning |
|---|---|
conversions | Matching events, so one visitor can count more than once |
visitors | Distinct visitors who converted |
conversionRate | visitors divided by all visitors in the period |
Add from and to to set the period. The default is the last 30 days. Bots are left out.
Goals apply to past data, since they're matched against stored events when you run the report.
Remove a goal
Remove a goal on the Goals page. A goal used by an A/B test can't be removed. Adding and removing goals appears in the change log.