게시된 프로젝트의 상위 페이지, 유입 도메인, 기기 유형, 방문자 국가를 조회합니다.
프로젝트 분석 분류 기준 조회
플랜:
Business 이상
스코프: projects:read
게시된 프로젝트에서 지정한 UTC 전체 날짜 범위의 상위 페이지, 유입 도메인, 기기 유형, 방문자 국가를 반환합니다. 각 분류 기준은 최대 10개 항목을 방문자 수가 높은 순서로 반환합니다. 날짜 범위는 최대 365일입니다. 일부 프로젝트는 분석 데이터를 90일 동안 보관하며, 그보다 오래된 날짜는 방문자 수에 반영되지 않습니다.
OpenAPI
| 항목 | 값 |
|---|---|
| Method | GET |
| Path | /v1/projects/{project_id}/analytics/breakdowns |
| Operation ID | getProjectAnalyticsBreakdowns |
| Source spec | https://api.lovable.dev/v1/openapi.yaml |
| Local snapshot | YAML 스냅샷 (SHA-256: c2391c63efb3cf43bcefd0f914048f6315c78f68e8a4c64e8855714865f97a90) |
GET /v1/projects/{project_id}/analytics/breakdowns인증
Lovable-API-Key: lov_your-api-key 또는 Authorization: Bearer <key>를 보냅니다. 키는 한 워크스페이스에 묶이며 public:v1 audience를 가집니다. 다른 워크스페이스의 리소스는 존재하지 않는 리소스와 마찬가지로 404를 반환합니다.
매개변수
| 이름 | 위치 | 필수 | 타입 | 설명 |
|---|---|---|---|---|
project_id | path | 예 | string | 프로젝트 ID입니다. |
starts_at | query | 예 | string, date-time | 시간 범위의 시작입니다. 2026-04-01T00:00:00Z 같은 RFC 3339 timestamp를 보냅니다. 어떤 오프셋이든 허용되며 UTC로 변환됩니다. 범위는 starts_at의 UTC 날짜부터 ends_at의 UTC 날짜까지 전체 UTC 달력 날짜를 포함합니다. |
ends_at | query | 예 | string, date-time | 시간 범위의 끝입니다. 2026-04-08T00:00:00Z 같은 RFC 3339 timestamp를 보냅니다. 어떤 오프셋이든 허용되며 UTC로 변환됩니다. |
Lovable-Version | header | 아니요 | string | 제공받을 안정 API 버전입니다. YYYY-MM-DD 날짜 형식으로 보냅니다. 생략하면 현재 가장 오래된 지원 안정 버전인 2026-09-11이 사용됩니다. |
Lovable-Beta | header | 아니요 | string | 안정 버전 위에 활성화할 베타 리비전 문자열입니다. 여러 개는 쉼표로 구분합니다. |
예시
curl --request GET \
--url 'https://api.lovable.dev/v1/projects/project-id/analytics/breakdowns?ends_at=2026-04-08T00:00:00Z&starts_at=2026-04-01T00:00:00Z' \
--header 'Lovable-API-Key: lov_your-api-key' \
--header 'Lovable-Version: 2026-09-11'const response = await fetch("https://api.lovable.dev/v1/projects/project-id/analytics/breakdowns?ends_at=2026-04-08T00:00:00Z&starts_at=2026-04-01T00:00:00Z", {
method: "GET",
headers: {
"Lovable-API-Key": process.env.LOVABLE_API_KEY ?? "lov_your-api-key",
"Lovable-Version": "2026-09-11",
},
});
if (!response.ok) {
throw new Error(`Lovable API ${response.status}: ${await response.text()}`);
}
console.log(await response.json());응답
| 상태 | 본문 | 설명 |
|---|---|---|
200 | ProjectAnalyticsBreakdowns | 요청이 성공했습니다. |
400 | ErrorResponse | 요청 본문 또는 매개변수 형식이 잘못되었거나 검증에 실패했습니다. 실패한 각 필드는 errors에 나열됩니다. |
401 | ErrorResponse | API 키, 세션 토큰 또는 OAuth access token이 없거나 유효하지 않습니다. |
402 | ErrorResponse | Public API 접근에는 Business 이상 플랜이 필요합니다. 일부 작업 또는 설정에는 추가 기능 권한이 필요할 수 있습니다. |
403 | ErrorResponse | 키 또는 호출자에게 필요한 스코프나 권한이 없습니다. email_not_verified라면 계정 이메일을 인증한 뒤 다시 시도하세요. |
404 | ErrorResponse | 프로젝트가 존재하지 않거나 삭제되었거나 인증된 클라이언트가 접근할 수 없습니다. 프로젝트가 게시되어 있지 않아도 분석을 사용할 수 없으므로 404가 반환됩니다. |
406 | ErrorResponse | Accept 헤더가 이 엔드포인트가 생성하는 모든 미디어 타입을 제외합니다. |
429 | ErrorResponse | 요청이 너무 많습니다. Retry-After가 있으면 해당 간격 뒤에 재시도합니다. |
503 | ErrorResponse | 서비스를 일시적으로 사용할 수 없거나 처리 기한이 만료되었습니다. 변이가 포함된 작업은 완료될 수 있으므로 재시도 전에 리소스 상태를 확인하세요. |
default | ErrorResponse | 오류입니다. 응답 본문은 표준 오류 envelope을 사용하며 status는 HTTP 상태 코드와 같고 type은 machine-readable 오류 코드입니다. |
응답 헤더
모든 응답에는 상황에 따라 다음 공통 헤더가 포함될 수 있습니다: Lovable-Version, Lovable-Beta, X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Lovable-Unknown-Query-Params, X-Lovable-Unknown-Query-Params-Omitted. X-Lovable-Unknown-Query-Params는 이 작업이 선언하지 않은 query parameter가 있을 때 URL escape된 이름을 최대 20개까지 쉼표로 제공하며, 20개를 넘으면 X-Lovable-Unknown-Query-Params-Omitted가 누락된 개수(minimum: 1)를 제공합니다. 401 응답은 string인 WWW-Authenticate를, 429 응답은 integer인 Retry-After를 포함합니다. Retry-After는 minimum: 1입니다. X-RateLimit-Reset은 지연 시간이 아니라 Unix timestamp 초 단위입니다.
스키마
ProjectAnalyticsBreakdowns
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
pages | AnalyticsBreakdownItem[] | 예 | 방문자 세션 기준 상위 페이지 경로입니다. 최대 10개이며 높은 값부터 낮은 값 순서입니다. |
sources | AnalyticsBreakdownItem[] | 예 | 방문자 세션 기준 상위 유입 도메인입니다. 최대 10개이며 높은 값부터 낮은 값 순서입니다. 유입 도메인이 기록되지 않은 경우 Direct를 뜻합니다. |
devices | AnalyticsBreakdownItem[] | 예 | 방문자 세션 기준 상위 기기 유형입니다. 최대 10개이며 높은 값부터 낮은 값 순서입니다. |
countries | AnalyticsBreakdownItem[] | 예 | 방문자 세션 기준 상위 방문자 국가입니다. 최대 10개이며 높은 값부터 낮은 값 순서입니다. 국가를 확인할 수 없으면 Unknown을 뜻합니다. |
AnalyticsBreakdownItem
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
label | string | 예 | 이 분류 기준 안에서 항목의 이름입니다. |
visitors | integer, int64 | 예 | 요청 범위에서 이 항목에 귀속된 고유 방문자 세션 수입니다. 한 세션이 여러 항목에 나타날 수 있습니다. |
ErrorResponse
공통 오류 응답입니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
detail | `string \ | null` | 예 |
errors | `array \ | null` | 예 |
props | `object \ | null` | 예 |
request_id | string | 예 | X-Request-Id 응답 헤더에서 반복되는 이 요청의 식별자입니다. |
status | integer | 예 | 본문에 반복되는 HTTP 상태 코드입니다. |
title | string | 예 | 사람이 읽을 수 있는 오류 요약입니다. |
type | string | 예 | 안정적인 machine-readable 오류 유형입니다. |
원본에 포함된 이 작업의 OpenAPI 스냅샷은 YAML 스냅샷 (SHA-256: c2391c63efb3cf43bcefd0f914048f6315c78f68e8a4c64e8855714865f97a90)로 보존했습니다. 최신 전체 OpenAPI 계약은 https://api.lovable.dev/v1/openapi.yaml에서 확인할 수 있습니다.