--- title: Analytics API url: https://platform.claude.com/docs/ko/manage-claude/analytics-api description: 조직에 필요한 분석 API와 API 키가 무엇인지 이해한 다음, Claude Code 생산성 지표 또는 Claude Enterprise 참여 및 도입 데이터에 대한 액세스를 프로비저닝하세요. --- Anthropic은 두 가지 제품 분석 API를 제공하며, 어느 것을 사용할지는 조직이 관리하는 Claude 제품에 따라 달라집니다: * **Claude Code Analytics API**는 Claude Platform을 사용하는 조직을 위해 일별 Claude Code 생산성 지표를 보고합니다. 이는 [Admin API](https://platform.claude.com/docs/ko/manage-claude/admin-api)의 일부이며 Admin API 키를 사용합니다. * **Claude Enterprise Analytics API**는 Claude Enterprise 조직을 위해 Claude 제품 전반(채팅, 프로젝트, Claude Code 등)에 걸친 조직 전체의 참여, 도입 및 비용 데이터를 보고합니다. 이는 claude.ai에서 생성한 Analytics API 키를 사용합니다. 두 API는 서로 다른 역할이 서로 다른 위치에서 생성하는 서로 다른 키 유형을 사용합니다. 이 페이지에서는 어떤 API가 조직에 적합한지, 그리고 올바른 키를 생성하는 방법을 설명합니다. ## 어떤 API가 필요한가요? | API | 키 유형 | 생성 위치 | 생성 가능한 사람 | 포함 범위 | | ----------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------- | | **Claude Code Analytics API** | Admin API 키 (`sk-ant-admin01-...`) | Claude Console의 [관리자 키](https://platform.claude.com/settings/admin-keys) 페이지 (`platform.claude.com/settings/admin-keys`) | 조직 관리자 | 사용자별 일별 Claude Code 지표: 세션, 코드 라인 수, 커밋, 풀 리퀘스트, 도구 수락, 모델별 예상 비용 | | **Claude Enterprise Analytics API** | Analytics API 키 | [claude.ai > 조직 설정 > API](https://claude.ai/admin-settings/api-access) | 주 소유자 | 조직 전체의 참여 및 도입(사용자 활동, 활성 사용자 요약, 프로젝트, 스킬 및 커넥터 사용량)과 비용 및 사용량 보고서 | 키 유형은 서로 호환되지 않습니다. Admin API 키로는 Claude Enterprise Analytics API를 호출할 수 없으며, Analytics API 키로는 Admin API를 호출할 수 없습니다. 유일한 예외는 [Usage and Cost Analytics API](https://platform.claude.com/docs/ko/manage-claude/usage-cost-analytics-api)로, Claude Enterprise 조직은 Analytics API 키로 이 API를 호출합니다. 두 제품 분석 API 모두 [Admin API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization) 아래에 표시되지만, 별도의 키 유형을 사용하는 별개의 API입니다. 조직에서 Claude Platform과 Claude Enterprise를 모두 사용하는 경우, 두 키를 모두 프로비저닝하고 각 API를 해당 데이터에 사용할 수 있습니다. 제품 분석이 아닌 토큰 사용량 및 비용 데이터를 찾고 계신가요? Claude Console 조직과 Claude Enterprise 조직 모두에 제공되는 [Usage and Cost Analytics API](https://platform.claude.com/docs/ko/manage-claude/usage-cost-analytics-api)를 참조하세요. 참여 및 도입 데이터를 프로그래밍 방식이 아닌 제품 내에서 보려면 claude.ai의 [Analytics 대시보드](https://claude.ai/analytics/activity)를 사용하세요. 거버넌스 및 감사 사용 사례(개별 사용자 작업, 원시 활동 이벤트, 대화 콘텐츠)의 경우 [Compliance API](https://platform.claude.com/docs/ko/manage-claude/compliance-api-access)를 참조하세요. ## Claude Code Analytics API 액세스 얻기 Claude Code Analytics API는 [Admin API](https://platform.claude.com/docs/ko/manage-claude/admin-api)에 액세스할 수 있는 모든 조직에서 사용할 수 있으며, 무료로 사용할 수 있습니다. [Admin API 키 생성](https://platform.claude.com/docs/ko/manage-claude/admin-api-keys#create-a-key-for-a-claude-console-organization)의 단계를 따르세요. `x-api-key` 헤더에 키를 전달하세요: ```bash curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2025-09-08" \ -H "anthropic-version: 2026-10-21" \ -H "x-api-key: $ANTHROPIC_ADMIN_KEY" ``` 사용 가능한 지표, 요청 매개변수 및 응답 스키마에 대해서는 [Claude Code Analytics API](https://platform.claude.com/docs/ko/manage-claude/claude-code-analytics-api) 가이드와 [API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization/usage_report/retrieve_claude_code)를 참조하세요. ## Claude Enterprise Analytics API 액세스 얻기 Claude Enterprise Analytics API는 Claude Enterprise 조직에서 사용할 수 있습니다. 참여 및 도입 데이터는 모든 Enterprise 플랜에서 사용할 수 있습니다. 비용 및 사용량 엔드포인트는 사용량 기반 Enterprise 플랜에 적용되며, 시트 기반 Enterprise 플랜의 경우 사용량 크레딧만 반영합니다. 조직의 기본 소유자만 API 액세스를 활성화하고 Analytics API 키를 생성할 수 있습니다. [claude.ai > 조직 설정 > API](https://claude.ai/admin-settings/api-access)로 이동하여 공개 API 액세스를 활성화한 다음 Analytics API 키를 생성하세요. 키에는 `read:analytics` 범위가 부여됩니다. 표시된 시크릿을 복사하여 시크릿 관리자에 저장하세요. `x-api-key` 헤더에 키를 전달하고, 모든 요청에 [`anthropic-version`](https://platform.claude.com/docs/ko/api/versioning) 헤더를 포함하세요. 엔드포인트는 `https://api.anthropic.com/v1/organizations/analytics/` 아래에 있습니다. 요청 예시, 매개변수 및 응답 스키마에 대해서는 [Claude Enterprise Analytics API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization/analytics)를 참조하세요. Claude Enterprise Analytics API는 다음을 제공합니다: * **사용자 활동:** 채팅(대화, 메시지, 프로젝트, 파일, 아티팩트), Claude Code(세션, 커밋, 풀 리퀘스트, 코드 라인 수, 도구 작업), Chat and Cowork unified(채팅 활동 및 Cowork 세션) 및 기타 Claude 제품 전반에 걸친 사용자별 일별 지표 * **활동 요약:** 조직 수준의 일별, 주별, 월별 활성 사용자, 시트 수 및 대기 중인 초대 * **프로젝트, 스킬 및 커넥터 사용량:** 채팅 프로젝트, 스킬 및 커넥터에 대한 도입 세부 내역 * **비용 및 사용량 보고서:** 시간 경과에 따른 사용자별 및 조직 수준의 토큰 사용량과 비용(사용량 기반 Enterprise 플랜) `/v1/organizations/analytics/` 아래의 비용 및 사용량 보고서 엔드포인트(`usage_report`, `cost_report`, `user_usage_report`, `user_cost_report`)는 레거시이며 계속 지원됩니다. 새로운 통합에는 [Usage and Cost Analytics API](https://platform.claude.com/docs/ko/manage-claude/usage-cost-analytics-api)를 사용하세요. 기존 통합을 이전하려면 [Claude Enterprise 사용량 및 비용 보고서에서 마이그레이션](https://platform.claude.com/docs/ko/manage-claude/usage-cost-analytics-api#migrate-from-enterprise-analytics-reports)을 참조하세요. 그 외의 Claude Enterprise Analytics API 엔드포인트는 레거시가 아닙니다. 엔드포인트 세부 정보, 매개변수 및 응답 스키마는 [Claude Enterprise Analytics API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization/analytics)를 참조하세요. 다음 섹션에서는 해당 엔드포인트 전반에 적용되는 데이터 최신성, 지표 정의 및 운영 지침을 다룹니다. ## 데이터 가용성 및 최신성 Claude Enterprise Analytics API 데이터는 2026년 1월 1일 이후 날짜에 대해 사용할 수 있습니다. **참여 및 도입 엔드포인트**(사용자 활동, 요약, 프로젝트, 스킬, 커넥터)는 지정한 날짜에 대한 일별 스냅샷을 반환합니다. 특정 날짜의 데이터는 일반적으로 다음 날 UTC 기준 약 13:00–13:30까지 사용할 수 있게 됩니다(1일 지연). 그 전까지는 사용 가능한 가장 최근 날짜가 보통 현재 UTC 날짜보다 2일 전입니다. 업스트림 데이터 파이프라인이 늦게 실행되는 날에는 데이터가 더 늦게 도착하며, 정확한 최신성은 쿼리마다 다릅니다. 고정된 시간을 가정하기보다는 오류 응답을 확인하세요: 아직 사용할 수 없는 날짜를 요청하면 사용 가능한 가장 최근 날짜를 명시한 400 오류가 반환됩니다. 일반적인 지연 시간을 훨씬 지나서도 데이터를 사용할 수 없다면, 이는 보통 Anthropic 측의 데이터 파이프라인 장애를 나타냅니다. 공백이 계속되면 지원팀에 문의하세요. **비용 및 사용량 엔드포인트**는 다른 최신성 모델을 따릅니다. 데이터는 일반적으로 기반이 되는 사용이 발생한 후 4시간 이내에 사용할 수 있지만 최대 24시간이 걸릴 수 있습니다. 늦게 도착하는 이벤트와 조정 작업이 실행됨에 따라, 역월 종료 후 약 7일까지 값이 수정될 수 있습니다. 예를 들어 10월 1일의 값은 약 11월 7일까지 변경될 수 있습니다. 청구서 수준의 합계가 필요하다면 종료된 지 최소 7일이 지난 월만 쿼리하세요. 비용 및 사용량 응답에는 `data_refreshed_at` 타임스탬프가 포함됩니다. `ending_at`을 생략하면 기본값은 `starting_at`으로부터 31일 후와 현재 시간 중 더 이른 시점입니다. 이 범위는 `data_refreshed_at`을 넘어설 수 있으며, 그 시점 이후의 데이터는 불완전합니다. 반복 호출에서 안정적인 결과를 얻으려면 `ending_at`을 이전에 반환된 `data_refreshed_at`과 같거나 그 이전의 값으로 설정하세요. ## 지표 정의 방식 **활성 사용자.** 다음 중 하나라도 해당하면 해당 날짜에 사용자가 활성 상태로 집계됩니다: * Claude에서 채팅 메시지를 하나 이상 보냈습니다. * Claude Enterprise 조직과 연결된 Claude Code 세션(로컬 또는 원격)을 하나 이상 가졌으며, 그 세션에 도구 사용 또는 git 활동이 포함되었습니다. * 도구 사용 또는 메시지 활동이 있는 Cowork 세션을 하나 이상 가졌습니다. **Chat and Cowork unified.** Chat and Cowork unified는 Cowork의 기능을 claude.ai 채팅으로 가져옵니다. Chat and Cowork unified의 대부분의 활동은 `chat` 또는 `cowork`가 아닌 `chat_cowork_unified` 제품 값으로 보고됩니다. 사용자 활동과 스킬, 커넥터 및 플러그인 사용량에서 이 사용량은 `chat_cowork_unified_metrics` 객체에 표시됩니다. 활동 요약에서는 `chat_cowork_unified_daily_active_user_count`, `chat_cowork_unified_weekly_active_user_count`, `chat_cowork_unified_monthly_active_user_count`에 집계됩니다. 사용자가 Chat and Cowork unified를 사용하기 시작하면, 해당 사용자의 사용량은 채팅 및 Cowork 수치에서 Chat and Cowork unified 수치로 이동합니다. 사용자가 Chat and Cowork unified를 사용하기 시작하기 전 날짜의 사용량은 그대로 채팅 또는 Cowork 수치에 남습니다. 총 토큰 사용량, 총 비용, 전체 활성 사용자 수와 같은 조직 전체 수치는 변경되지 않습니다. 제품별로 필터링된 비용 및 사용량 보고서는 `products[]`에 `chat_cowork_unified`가 포함되지 않는 한 Chat and Cowork unified 사용량을 제외합니다. 음성 모드와 같은 Chat and Cowork unified 사용자의 일부 활동은 여전히 채팅 또는 Cowork로 보고될 수 있습니다. 또한 사용자가 Chat and Cowork unified를 사용하기 시작한 날에는 사용자의 활동이 여러 제품으로 나뉠 수 있습니다. 해당 사용자에 대해 이 기능이 꺼진 날에도 마찬가지입니다. 활동이 어떻게 나뉘는지는 보장되지 않습니다. 사용자는 채팅 또는 Cowork 집계와 Chat and Cowork unified 집계 모두에 나타날 수 있습니다. 이는 사용자가 Chat and Cowork unified를 사용하면서도 일부 활동이 여전히 채팅 또는 Cowork 아래에 보고되는 날에 발생할 수 있습니다. 주간 및 월간 집계는 해당 기간에 두 종류의 활동이 모두 있는 경우, 서로 다른 날이더라도 사용자를 양쪽 모두에 포함할 수 있습니다. 예를 들어, 해당 기간이 사용자가 Chat and Cowork unified를 사용하기 시작하기 전과 후의 날짜를 모두 포함할 수 있습니다. 프로젝트별로 사용자 활동을 필터링하면 각 날짜의 프로젝트 활동은 한 곳에서만 집계됩니다. 사용자가 그날 Chat and Cowork unified에서 채팅 메시지를 보냈다면, 해당 사용자의 모든 프로젝트 활동은 `chat_cowork_unified_metrics.chat`에 집계됩니다. 그렇지 않으면 `chat_metrics`에 집계됩니다. **제품별 지표 블록.** 제품별 지표 객체(예: 사용자 활동 레코드의 Office Agent 또는 Cowork 지표)는 모든 레코드에 항상 존재합니다. 해당 제품의 사용량이 없는 조직에는 `null` 객체 대신 개수가 0으로 표시됩니다. 예외는 Chat and Cowork unified로, 이를 제공하지 않는 배포 환경에서는 해당 필드가 응답에서 제외됩니다. 이러한 객체 내부의 개별 필드는 `null`일 수 있으며, 이는 해당 값을 사용할 수 없음을 의미합니다. 예를 들어, 프로젝트별로 사용자 활동을 필터링하면 `chat_metrics`의 `distinct_skills_used_count`는 `null`입니다. 어떤 필드가 `null`일 수 있는지는 [Claude Enterprise Analytics API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization/analytics)에서 확인할 수 있습니다. **커넥터 이름.** 커넥터 이름은 소스 전반에 걸쳐 정규화됩니다. 예를 들어 `Atlassian MCP server`, `mcp-atlassian`, `atlassian_MCP`는 모두 커넥터 사용량 엔드포인트에서 `atlassian`으로 표시됩니다. ## API 사용하기 **페이지네이션 커서는 이를 발급한 쿼리에 바인딩됩니다.** 비용 및 사용량 엔드포인트에서는 시퀀스 중간에 쿼리 매개변수를 변경하지 마세요. `products[]`, `group_by[]`, `order_by`, 날짜 범위 또는 필터를 변경하고 이전 커서를 전달하면 요청은 400 오류를 반환합니다. 매개변수를 변경하려면 커서 없이 첫 페이지부터 다시 시작하세요. **목록 매개변수는 대괄호 표기법을 사용합니다.** 각 값에 대해 매개변수를 반복하세요. 예: `products[]=chat&products[]=claude_code`. **금액 필드는 센트 단위의 10진수 문자열입니다.** 통화 금액은 `"41280.000000"`(USD $412.80을 나타냄)과 같은 10진수 문자열로 반환됩니다. 달러로 변환하려면 10진수로 파싱한 후 100으로 나누세요. 수백만 달러를 초과할 수 있는 값에는 이진 부동소수점 파싱을 피하세요. **속도 제한은 키별이 아닌 조직 수준에서 적용되며**, 이 API의 모든 엔드포인트에 걸쳐 기본값은 분당 60개 요청입니다. 이것이 사용 사례에 충분하지 않은 경우, Anthropic 계정 팀에 문의하여 제한 조정을 논의하세요. ## 버전 관리 모든 요청에 `anthropic-version` 헤더를 보내세요. 사용 가능한 버전은 [버전](https://platform.claude.com/docs/ko/api/versioning)을 참조하세요. ## 알려진 제한 사항 ### Amazon Bedrock을 통한 Claude Code 조직에서 Amazon Bedrock을 통해 Claude Code를 사용하는 경우, Claude Enterprise Analytics API는 해당 사용에 대한 Claude Code 활동을 반환하지 않습니다. ### 고객 관리형 암호화 키를 사용하는 Claude Code 및 Cowork 조직에서 [고객 관리형 암호화 키](https://platform.claude.com/docs/ko/manage-claude/cmek)를 사용하는 경우, Anthropic은 데이터를 보호하기 위해 Claude Code 및 Cowork 사용의 일부 세부 정보를 사용량 분석에서 제외합니다. 따라서 조직의 Claude Code 또는 Cowork 사용량을 측정하는 데 다음 Claude Enterprise Analytics API 수치를 사용하지 마세요. 이 수치는 0이거나 실제 사용량보다 낮을 수 있습니다: * **코드 변경:** 사용자 활동에서 `claude_code_metrics.core_metrics`의 다음 필드는 0일 수 있습니다: `lines_of_code`(추가 및 삭제된 줄)와 `commit_count`. `pull_request_count` 필드는 실제 풀 리퀘스트 수보다 낮을 수 있습니다. * **슬래시 명령으로 시작한 스킬:** 사용자가 `/skill-name`과 같은 슬래시 명령을 입력하여 Claude Code 또는 Cowork에서 스킬을 시작하면 해당 사용은 집계되지 않습니다. 이는 스킬 사용량과 사용자 활동의 Cowork 스킬 집계에 적용됩니다. Claude가 슬래시 명령 없이 호출하는 스킬은 계속 집계됩니다. 고객 관리형 암호화 키와 관련된 기타 분석 변경 사항은 [Claude Enterprise에서 CMEK가 보호하는 항목](https://platform.claude.com/docs/ko/manage-claude/cmek-coverage-claude-enterprise#turned-off-or-changed)을 참조하세요. ## 다음 단계 Admin API 키로 Claude Code 세션, 코드 변경 사항 및 도구 사용량을 추적하세요. 조직의 토큰 사용량과 비용을 추적하세요. 참여, 도입 및 비용 데이터에 대한 엔드포인트 레퍼런스입니다. 감사 및 규정 준수 데이터는 자체 키 유형을 사용합니다.