> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Query API

> Read analytics reports over REST with an API key: KPIs, timeseries, top lists, lifecycle, retention, funnels, user paths, attribution and profiles.

The Query API gives you the reports of the dashboard and the [MCP server](https://docs.manalens.dev/mcp/overview.md) as plain HTTP endpoints. Use it to pull your numbers into a script, a spreadsheet or your own tools.

Each endpoint uses the same report code as the MCP tool or the dashboard report, so the numbers match.

## Authentication

Use an [API key](https://docs.manalens.dev/api/authentication.md#api-keys) (`mana_api_...`) in the `Authorization` header:

```bash theme={null}
curl -sS "https://api.manalens.dev/v0/projects/$PROJECT_ID/query/kpis?date_from=2026-11-01&date_to=2026-11-30" \
  -H "Authorization: Bearer $MANALENS_API_KEY"
```

* The key works on its own project only. A key of another project gets `404`.
* The key needs the scope of the endpoint. Without it, the response is `403` `FORBIDDEN`, and the message names the scope.
* Call the API from a server. A request with a browser `Origin` header gets `403`.
* The key shares its rate limits with the MCP server: 120 requests per minute per key, and 600 per minute per workspace.

## Endpoints

| Endpoint | Method | Scope |
| - | - | - |
| [KPIs](https://docs.manalens.dev/api/query/kpis.md) | `GET /query/kpis` | `analytics:read` |
| [Event timeseries](https://docs.manalens.dev/api/query/event-timeseries.md) | `GET /query/event-timeseries` | `analytics:read` |
| [Top pages](https://docs.manalens.dev/api/query/top-pages.md) | `GET /query/top-pages` | `analytics:read` |
| [Top sources](https://docs.manalens.dev/api/query/top-sources.md) | `GET /query/top-sources` | `analytics:read` |
| [Top locations](https://docs.manalens.dev/api/query/top-locations.md) | `GET /query/top-locations` | `analytics:read` |
| [Top events](https://docs.manalens.dev/api/query/top-events.md) | `GET /query/top-events` | `analytics:read` |
| [User lifecycle](https://docs.manalens.dev/api/query/user-lifecycle.md) | `GET /query/user-lifecycle` | `analytics:read` |
| [User frequency](https://docs.manalens.dev/api/query/user-frequency.md) | `GET /query/user-frequency` | `analytics:read` |
| [Retention](https://docs.manalens.dev/api/query/retention.md) | `GET /query/retention` | `analytics:read` |
| [Funnel](https://docs.manalens.dev/api/query/funnel.md) | `POST /query/funnel` | `analytics:read` |
| [User flow](https://docs.manalens.dev/api/query/flow.md) | `POST /query/flow` | `analytics:read` |
| [Attribution](https://docs.manalens.dev/api/query/attribution.md) | `GET /query/attribution` | `attribution:read` |
| [Profile](https://docs.manalens.dev/api/query/profile.md) | `GET /query/profiles/{userId}` | `profiles:read` |

Every path starts with `/v0/projects/{projectId}`.

## Filters

The report endpoints take the same filters:

* `date_from` and `date_to` as `YYYY-MM-DD` (UTC). The default is the last 30 days. A range is at most 367 days.
* Context filters, for example `utm_source`, `channel_type`, `country`, `device` and `page_path`.
* `filters`: operator filters as `{ "field", "op", "value" }` objects, combined with AND. On a `GET` endpoint, send them as a JSON array in the query string. On a `POST` endpoint, send them as an array in the body.

```bash theme={null}
curl -sS -G "https://api.manalens.dev/v0/projects/$PROJECT_ID/query/top-pages" \
  -H "Authorization: Bearer $MANALENS_API_KEY" \
  --data-urlencode 'filters=[{"field":"country","op":"in","value":["SG","MY"]}]'
```

Parameters that an endpoint does not list are ignored.

## Responses

A report returns the resource with no envelope:

```json theme={null}
{
  "date_from": "2026-11-01",
  "date_to": "2026-11-30",
  "rows": [{ "visitors": 1204, "pageviews": 5310, "sessions": 1630 }]
}
```

* `date_from` and `date_to` are the range of the report, also when you leave them out.
* `rows` are the report rows.
* `totals` (event timeseries only) has the totals for the range.
* `notes` has fixed sentences on how to read the session columns, when a filter changes them.

Errors use the [error format](https://docs.manalens.dev/api/errors.md). Bad input gets `400` `INVALID_QUERY`, and the message names the parameter.

## OpenAPI

The API reference pages come from an OpenAPI 3.1 document. The API code generates it from the same schemas that check each request, so the reference and the API stay the same. It covers the events, profile properties and Query API endpoints.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.