분석 API

분석(Analytics) API는 연결된 SNS 채널들의 누적 성과, 시계열 팔로워 지표, 게시물 인게이지먼트 통계를 조회할 수 있는 인터페이스를 제공합니다.

📌 엔드포인트 목록

메서드	경로	설명	필요 스코프
`GET`	`/v1/brand/analytics`	특정 기간/플랫폼/연결별 성과 지표 상세 조회	`analytics:read` 또는 `*`
`GET`	`/v1/brand/analytics/overview`	브랜드 전체 채널의 30일 핵심 지표 요약 조회	`analytics:read` 또는 `*`

📊 상세 분석 조회 (`GET /v1/brand/analytics`)

선택한 기간과 필터 조건에 따른 상세 지표를 조회합니다.

쿼리 파라미터

파라미터	타입	필수 여부	기본값	설명
`range`	`string`	선택	`30d`	조회 기간 (`7d`, `14d`, `30d`, `90d` 또는 `YYYY-MM-DD..YYYY-MM-DD`)
`sns_type`	`string`	선택	-	특정 SNS 플랫폼으로 필터링 (`instagram`, `threads`, `bluesky` 등)
`connection_id`	`string`	선택	-	특정 SNS 연결 계정 ID로 필터링

요청 예시

curl -X GET "https://api.ankk.app/v1/brand/analytics?range=30d&sns_type=instagram" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

응답 예시 (`200 OK`)

{
  "range": {
    "start": "2026-07-17T00:00:00Z",
    "end": "2026-08-16T00:00:00Z",
    "preset": "30d"
  },
  "totals": {
    "followers": 12500,
    "followers_change": 340,
    "published_posts": 28,
    "impressions": 84200,
    "reach": 61500,
    "engagement_rate": 4.8,
    "likes": 3210,
    "comments": 412,
    "shares": 180,
    "saves": 250
  },
  "by_channel": [
    {
      "connection_id": "conn_01jm8x9k2example",
      "sns_type": "instagram",
      "username": "acme_official",
      "followers": 12500,
      "posts_count": 28,
      "metrics_status": "synced"
    }
  ]
}

📈 브랜드 개요 요약 (`GET /v1/brand/analytics/overview`)

대시보드 위젯이나 일일 리포트용으로 브랜드 전체 채널의 30일 핵심 지표를 빠르게 조회합니다.

요청 예시

curl -X GET "https://api.ankk.app/v1/brand/analytics/overview" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

응답 예시 (`200 OK`)

{
  "brand_ref": "brand_01jm8v4k9example",
  "active_connections": 4,
  "summary_30d": {
    "total_published": 54,
    "total_failed": 1,
    "total_followers": 28400,
    "total_impressions": 195000
  },
  "synced_at": "2026-08-16T03:00:00Z"
}

⚠️ 지표 수집 및 한도 안내

요금제별 조회 한도: Free 플랜은 최근 30일 지표만 조회 가능하며, Growth 플랜 이상에서 장기 시계열(90일+) 조회가 제공됩니다.
수치 0과 null의 차이:
- 0: 해당 플랫폼에서 측정된 실제 값이 0인 경우입니다.
- null / unsupported: 해당 플랫폼 API 정책상 해당 지표를 미지원하거나 권한이 없는 경우입니다.

🔗 관련 문서