# Goals, experiments and behaviour

<!-- docs-test setup: owner -->

Goals and A/B tests are part of a site's settings; their results come from the same data as the dashboard's
Behaviour view. How to send events and mark experiments in a page is in
[Goals and A/B tests](../goals-and-experiments.md).

Reading the lists needs `sites:read`, changing them `sites:write`, and results `analytics:read`.

| Route | Scope |
|---|---|
| `GET /v1/sites/{id}/goals` | `sites:read` |
| `POST /v1/sites/{id}/goals` | `sites:write` |
| `DELETE /v1/sites/{id}/goals/{goal}` | `sites:write` |
| `GET /v1/sites/{id}/goals/results` | `analytics:read` |
| `GET /v1/sites/{id}/experiments` | `sites:read` |
| `POST /v1/sites/{id}/experiments` | `sites:write` |
| `PATCH /v1/sites/{id}/experiments/{key}` | `sites:write` |
| `DELETE /v1/sites/{id}/experiments/{key}` | `sites:write` |
| `GET /v1/sites/{id}/experiments/{key}/results` | `analytics:read` |
| `GET /v1/sites/{id}/journeys` | `analytics:read` |

```sh
curl https://api.usherstats.com/v1/sites \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop", "hostnames": ["shop.example"]}'
```
<!-- expect 201; SITE_ID=.site.id -->

## Goals

A goal is an event, by name (`"type": "event"`), or a page (`"type": "path"`; a trailing `*` matches every path
that starts with the rest). Its `id`, made from its name, is what results use.

```sh
curl https://api.usherstats.com/v1/sites/$SITE_ID/goals \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Signup", "type": "event", "match": "signup"}'
```
<!-- expect 201 -->

```sh
curl https://api.usherstats.com/v1/sites/$SITE_ID/goals \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pricing page", "type": "path", "match": "/pricing*"}'
```
<!-- expect 201 -->

```sh
curl https://api.usherstats.com/v1/sites/$SITE_ID/goals \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

Results count each goal's completions (the events sent, or the page's pageviews), and for an event goal the People
sessions that reached it, out of all People visits:

```sh
curl "https://api.usherstats.com/v1/sites/$SITE_ID/goals/results?days=30" \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

`DELETE` removes one by its id. A goal reads the events already stored, so one added today counts last week's
sessions too. To replace every goal at once, `PATCH /v1/sites/{id}/settings` with a `goals` list.

```sh
curl -X DELETE https://api.usherstats.com/v1/sites/$SITE_ID/goals/pricing-page   -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 204 -->

## Experiments

An experiment's `key` is the `data-exp` name in your page. It needs at least two variants.

```sh
curl https://api.usherstats.com/v1/sites/$SITE_ID/experiments \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "hero-headline", "name": "Hero headline", "variants": ["a", "b"], "status": "running"}'
```
<!-- expect 201 -->

```sh
curl https://api.usherstats.com/v1/sites/$SITE_ID/experiments \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

Results, variant by variant: the People sessions shown it, how many reached the goal (`?goal=`, a goal id; the first
event goal by default), the rate, the events sent from it, and `p`, a two-proportion test between the two largest
variants. A variant seen by fewer than five sessions is listed without its figures, and `p` waits until both of the
two largest have five.

```sh
curl "https://api.usherstats.com/v1/sites/$SITE_ID/experiments/hero-headline/results?days=30&goal=signup" \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

```sh
curl -X PATCH https://api.usherstats.com/v1/sites/$SITE_ID/experiments/hero-headline \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "stopped"}'
```
<!-- expect 200 -->

```sh
curl https://api.usherstats.com/v1/sites/$SITE_ID/experiments   -H "Authorization: Bearer $US_TOKEN"   -H "Content-Type: application/json"   -d '{"key": "pricing-table", "variants": ["control", "annual-first"], "status": "draft"}'
```
<!-- expect 201 -->

```sh
curl -X DELETE https://api.usherstats.com/v1/sites/$SITE_ID/experiments/pricing-table \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 204 -->

## Behaviour

The Behaviour view's analysis: visits and goal rates, a Sankey of how sessions unfold (`?anchor=` centres it on one
step), the common paths with their lift on a goal, and every A/B test. `?zoom=` is `page`, `section` (the default) or
`element`; `?who=` is `human` (the default) or `internal`, your own team's sessions, for QA. A group of fewer than five
sessions is never named.

```sh
curl "https://api.usherstats.com/v1/sites/$SITE_ID/journeys?days=7&zoom=page" \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->