---
title: "Get project analytics breakdowns"
method: GET
path: "/v1/projects/{project_id}/analytics/breakdowns"
tags: ["analytics"]
---

# Get project analytics breakdowns

`GET /v1/projects/{project_id}/analytics/breakdowns`

## Request

- Base URL: `https://api.lovable.dev`
- URL: `https://api.lovable.dev/v1/projects/{project_id}/analytics/breakdowns`
- Auth: one of:
  - API key in header `Lovable-API-Key`
  - HTTP bearer

**Plan:** `Business or higher`

**Scope:** `projects:read`

Returns the top pages, referring domains, device types, and visitor countries for a published project over a range of complete UTC calendar dates, up to 10 items each. Date ranges are limited to 365 days. Some projects retain analytics for 90 days; older days contribute no visitors.

## Path parameters

- `project_id` string, required: Project ID.

## Query parameters

- `starts_at` string, date-time, required: Start of the time range as an RFC 3339 timestamp, such as 2026-04-01T00:00:00Z. Any offset is accepted and converted to UTC; the range covers complete UTC calendar dates from the UTC date of starts_at through the UTC date of ends_at.
- `ends_at` string, date-time, required: End of the time range as an RFC 3339 timestamp, such as 2026-04-08T00:00:00Z. Any offset is accepted and converted to UTC; the range covers complete UTC calendar dates from the UTC date of starts_at through the UTC date of ends_at.

## Headers

- `Lovable-Version` string
- `Lovable-Beta` string

## Response `200`

OK

- ProjectAnalyticsBreakdowns
  - `countries` AnalyticsBreakdownItem[], required: Top visitor countries by visitor sessions, up to 10 items ordered from highest to lowest. Unknown means the country could not be determined.
    - `label` string, required: Name of this item within the breakdown.
    - `visitors` integer, required: Unique visitor sessions attributed to this item over the requested range. A session can appear under multiple items.
  - `devices` AnalyticsBreakdownItem[], required: Top device types by visitor sessions, up to 10 items ordered from highest to lowest.
    - `label` string, required: Name of this item within the breakdown.
    - `visitors` integer, required: Unique visitor sessions attributed to this item over the requested range. A session can appear under multiple items.
  - `pages` AnalyticsBreakdownItem[], required: Top page paths by visitor sessions, up to 10 items ordered from highest to lowest.
    - `label` string, required: Name of this item within the breakdown.
    - `visitors` integer, required: Unique visitor sessions attributed to this item over the requested range. A session can appear under multiple items.
  - `sources` AnalyticsBreakdownItem[], required: Top referring domains by visitor sessions, up to 10 items ordered from highest to lowest. Direct means no referring domain was recorded.
    - `label` string, required: Name of this item within the breakdown.
    - `visitors` integer, required: Unique visitor sessions attributed to this item over the requested range. A session can appear under multiple items.

## Other responses

- `400`: The request body or parameters are malformed or fail validation. Each failing field is listed in errors.
- `401`: Missing or invalid API key, session token, or OAuth access token.
- `402`: Public API access requires Business or higher. Some operations or configurations require an additional feature entitlement.
- `403`: The key or caller lacks the required scope or permission. For email_not_verified, verify the account email before retrying.
- `404`: The project does not exist, has been deleted, or is not accessible to the authenticated client. Analytics are also unavailable when the project is not published.
- `406`: The Accept header excludes every media type this endpoint produces.
- `429`: Too many requests. Retry after the interval in Retry-After when present.
- `503`: The service is temporarily unavailable, or the processing deadline expired (request_timeout). A mutation may still complete; check resource state before retrying.
- `default`: Error. The response body uses the standard error envelope; status matches the HTTP status code and type is a machine-readable error code.

## Changes

- **2026-09-18** `a83f0776a896`: 2 breaking, 2 warning, 2 info
  - added the new required `query` request parameter `ends_at`
  - added the new required `query` request parameter `starts_at`
  - deleted the `query` request parameter `end_date`
  - deleted the `query` request parameter `start_date`
  - …2 more
- **2026-09-17** `63e95b862209`: 1 info
  - added the non-success response with the status `404`
- **2026-09-16** `1eba97261efb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lovable/apis/lovable-api/changes/v1/projects/:project_id/analytics/breakdowns/get.md)

---

[API](https://skmtc.dev/lovable/apis/lovable-api.md) - [All operations](https://skmtc.dev/lovable/apis/lovable-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lovable/apis/lovable-api/revisions/ed671816c468?raw)