# Insights

URL: https://pieowl.com/docs/api/insights



Authentication [#authentication]

Requires a `read` or `root` client. The default `write` client does not have access. See the [Authentication](/docs/api/authentication) guide.

Base URL [#base-url]

```
https://api.pieowl.com/insights/{projectId}
```

`{projectId}` is your site ID.

Example [#example]

```bash
curl 'https://api.pieowl.com/insights/YOUR_PROJECT_ID/metrics?range=30d' \
  -H 'pieowl-client-id: YOUR_CLIENT_ID' \
  -H 'pieowl-client-secret: YOUR_CLIENT_SECRET'
```

Common endpoints [#common-endpoints]

| Endpoint                                             | What it returns                                   |
| ---------------------------------------------------- | ------------------------------------------------- |
| `GET /metrics`                                       | Sessions, pageviews, bounce rate and other totals |
| `GET /live`                                          | The number of visitors on your site right now     |
| `GET /pages`                                         | Top pages                                         |
| `GET /referrer`, `/referrer_name`, `/referrer_type`  | Traffic sources                                   |
| `GET /country`, `/region`, `/city`                   | Location breakdown                                |
| `GET /device`, `/browser`, `/os`                     | Device and technology breakdown                   |
| `GET /utm_source`, `/utm_medium`, `/utm_campaign`, … | UTM parameter breakdown                           |
| `GET /funnel`                                        | Conversion for a sequence of events               |
| `GET /retention`                                     | Retention over time                               |

There are more endpoints for events, profiles, sessions, groups, saved reports and Google Search Console data. The [API Reference](/docs/api-reference) lists them all.

Query parameters [#query-parameters]

Most endpoints accept:

* `range`: a preset such as `today`, `7d`, `30d`, `3m`, `6m` or `12m`. The default is `7d`.
* `startDate` and `endDate`: a custom date range.
* `filters`: a JSON array of filters.
* `cursor` and `limit`: paging for list endpoints.

For full schemas, see the [API Reference](/docs/api-reference).