Analytics APIs

Analytics APIs

Anthropic은 두 가지 분석 API를 제공하며, 어떤 것을 사용할지는 조직이 관리하는 Claude 제품에 따라 달라져요. 이 페이지에서는 조직에 맞는 API가 무엇인지, 그리고 올바른 키를 만드는 방법을 설명해 드릴게요.

• Claude Code Analytics API는 Claude Platform을 사용하는 조직의 일별 Claude Code 생산성 지표를 보고해요. Admin API의 일부이며 Admin API 키를 사용해요.
• Claude Enterprise Analytics API는 Claude Enterprise 조직의 조직 전반 참여·도입·비용 데이터(채팅, 프로젝트, Claude Code 등)를 보고해요. claude.ai에서 만든 Analytics API 키를 사용해요.

두 API는 서로 다른 키 유형을 사용하고, 서로 다른 위치에서 다른 역할이 만들 수 있어요.

출처: 문서

본문

어떤 API가 필요한가요?

키 유형은 서로 호환되지 않아요. Admin API 키는 Claude Enterprise Analytics API를 호출할 수 없고, Analytics API 키는 Admin API를 호출할 수 없어요. 두 API 모두 Admin API 참조 아래에 나타나지만, 서로 다른 키 유형을 가진 별개의 API예요. 조직이 Claude Platform과 Claude Enterprise를 모두 사용한다면 두 키를 모두 발급하고 각 API를 자체 데이터에 사용할 수 있어요.

제품 분석이 아니라 API 사용량·비용 데이터를 찾고 있나요? Usage and Cost API를 참고하세요. Claude Console과 Claude Enterprise 조직 모두에 맞는 경로를 설명해 드려요.

참여·도입 데이터를 프로그래밍 방식이 아니라 제품에서 보려면 claude.ai의 Analytics 대시보드를 사용하세요. 거버넌스·감사 사용 사례(개별 사용자 작업, 원시 활동 이벤트, 대화 콘텐츠)는 Compliance API를 참고하세요.

Claude Code Analytics API 접근 권한 얻기

Claude Code Analytics API는 Admin API에 접근할 수 있는 모든 조직에서 사용할 수 있고, 무료로 이용할 수 있어요.

1. Admin API 키 만들기 — Admin API 키 만들기의 단계를 따르세요.

2. API 호출하기 — x-api-key 헤더에 키를 전달하세요:

   curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2025-09-08" \
     --header "anthropic-version: 2023-06-01" \
     --header "x-api-key: $ANTHROPIC_API_KEY"
   

가능한 지표, 요청 매개변수, 응답 스키마는 Claude Code Analytics API 가이드와 API 참조를 참고하세요.

Claude Enterprise Analytics API 접근 권한 얻기

Claude Enterprise Analytics API는 Claude Enterprise 조직에서 사용할 수 있어요. 참여·도입 데이터는 모든 Enterprise 요금제에서 사용할 수 있어요. 비용·사용량 엔드포인트는 사용량 기반 Enterprise 요금제에 적용되며, 좌석 기반 Enterprise 요금제에서는 사용 크레딧만 반영해요.

1. primary owner로 로그인 — 조직의 primary owner만 API 접근을 활성화하고 Analytics API 키를 만들 수 있어요.
2. API 접근 활성화 및 키 만들기 — claude.ai > Organization settings > API로 이동해 공개 API 접근을 활성화한 뒤 Analytics API 키를 만드세요. 키는 read:analytics 범위를 가져요. 표시된 비밀을 복사해 비밀 관리자에 저장하세요.
3. API 호출하기 — x-api-key 헤더에 키를 전달하고 모든 요청에 anthropic-version 헤더를 포함하세요. 엔드포인트는 https://api.anthropic.com/v1/organizations/analytics/ 아래에 있어요. 요청 예시, 매개변수, 응답 스키마는 Claude Enterprise Analytics API 참조를 참고하세요.

Claude Enterprise Analytics API는 다음을 제공해요:

• 사용자 활동: 채팅(대화, 메시지, 프로젝트, 파일, 아티팩트), Claude Code(세션, 커밋, 풀 리퀘스트, 코드 줄, 도구 작업), 기타 Claude 제품 전반의 사용자별 일별 지표
• 활동 요약: 조직 수준의 일별·주별·월별 활성 사용자, 좌석 수, 보류 중인 초대
• 프로젝트·스킬·커넥터 사용: 채팅 프로젝트, 스킬, 커넥터의 도입 세부 내역
• 비용·사용량 보고서: 시간 경과에 따른 사용자별·조직 수준 토큰 사용량과 비용(사용량 기반 Enterprise 요금제)

엔드포인트 상세, 매개변수, 응답 스키마는 Claude Enterprise Analytics API 참조를 참고하세요. 아래 섹션들은 해당 엔드포인트 전반에 적용되는 데이터 신선도, 지표 정의, 운영 가이드를 다뤄요.

데이터 가용성과 신선도

Claude Enterprise Analytics API 데이터는 2026년 1월 1일 이후의 날짜에 대해 사용할 수 있어요.

참여·도입 엔드포인트(사용자 활동, 요약, 프로젝트, 스킬, 커넥터)는 지정한 날짜의 일별 스냅샷을 반환해요. 특정 날짜의 데이터는 보통 다음 날 약 17:00 UTC부터 사용할 수 있어요(1일 지연). 그 전까지는 가장 최근 사용 가능한 날이 현재 UTC 날짜보다 이틀 전인 경우가 많아요. 데이터가 가끔 늦게 도착하고 정확한 신선도는 조회에 따라 달라지므로 고정된 시간을 가정하지 말고 오류 응답을 확인하세요. 아직 사용할 수 없는 날짜를 요청하면 가장 최근 사용 가능한 날을 알려주는 400 오류가 반환돼요. 일반적인 지연을 지나 한참 동안 데이터가 없으면 보통 Anthropic 쪽 데이터 파이프라인 실패를 의미해요. 격차가 지속되면 지원에 문의하세요.

비용·사용량 엔드포인트는 다른 신선도 모델을 따라요. 데이터는 보통 기본 사용량 발생 후 4시간 이내에 사용할 수 있지만 최대 24시간까지 걸릴 수 있어요. 특정 날짜의 값은 늦은 이벤트가 도착하고 조정이 실행되면서 최대 30일 동안 수정될 수 있어요. 청구서 등급 총액이 필요하다면 최소 30일 이전 날짜를 조회하세요.

비용·사용량 응답에는 data_refreshed_at 타임스탬프가 포함돼요. ending_at을 생략하면(기본값은 현재 시각) 응답에 data_refreshed_at 이후의 불완전한 꼬리 데이터가 포함돼요. 반복 호출에서 안정적인 결과를 얻으려면 ending_at을 이전에 반환된 data_refreshed_at과 같거나 이전 값으로 설정하세요.

지표는 어떻게 정의되나요?

활성 사용자. 다음 중 하나라도 해당하면 사용자는 그날 활성으로 간주돼요: Claude에서 채팅 메시지를 하나 이상 보냈거나, 도구 사용 또는 git 활동을 포함한 Claude Code 세션(로컬 또는 원격)이 조직과 연결되어 있거나, 도구 사용 또는 메시지 활동이 있는 Cowork 세션이 하나 이상 있거나.

제품별 지표 블록. 제품별 지표 객체(예: 사용자 활동 기록의 Office Agent 또는 Cowork 지표)는 항상 모든 기록에 존재해요. 해당 제품을 사용하지 않는 조직은 null이 아니라 모두 0인 값을 보게 돼요.

커넥터 이름. 커넥터 이름은 출처 간에 정규화돼요. 예를 들어 Atlassian MCP server, mcp-atlassian, atlassian_MCP는 모두 커넥터 사용 엔드포인트에서 atlassian으로 나타나요.

API 사용하기

페이지네이션 커서는 이를 발급한 조회에 바인딩돼요. 비용·사용량 엔드포인트에서 시퀀스 중에 조회 매개변수를 변경하지 마세요: products[], group_by[], order_by, 날짜 범위 또는 필터를 변경하면서 이전 커서를 전달하면 400 오류가 반환돼요. 매개변수를 변경하려면 커서 없이 첫 페이지부터 다시 시작하세요.

목록 매개변수는 괄호 표기법을 사용해요. 값마다 매개변수를 반복하세요. 예: products[]=chat&products[]=claude_code.

금액 필드는 센트 단위의 십진 문자열이에요. 통화 금액은 "41280.000000"(412.80달러를 나타냄) 같은 십진 문자열로 반환돼요. 달러로 변환하려면 십진수로 파싱한 뒤 100으로 나누세요. 수백만 달러를 초과할 수 있는 값에는 이진 부동소수점 파싱을 피하세요.

요금 한도는 키가 아니라 조직 수준에서 적용돼요. 이 API의 모든 엔드포인트에서 기본적으로 분당 60회 요청이에요. 사용 사례에 충분하지 않다면 한도 조정을 논의하려면 Anthropic 계정 팀에 문의하세요.

버전 관리

모든 요청에 anthropic-version 헤더를 보내세요. 사용 가능한 버전은 API 버전을 참고하세요.

알려진 제한 사항

조직이 Amazon Bedrock을 통해 Claude Code를 사용한다면, Claude Enterprise Analytics API는 해당 사용에 대한 Claude Code 활동을 반환하지 않아요.

다음 단계

• Claude Code Analytics API — 이동 — Admin API 키로 Claude Code 세션, 코드 변경, 도구 사용을 추적하세요.
• Usage and Cost API — 이동 — 조직의 API 토큰 사용량과 비용을 추적하세요.
• Claude Enterprise Analytics API 참조 — 이동 — 참여·도입·비용 데이터의 엔드포인트 참조.
• Compliance API 설정 — 이동 — 감사·준수 데이터는 자체 키 유형을 사용해요.

더 알아보기 (Learn more)

• Claude Code Analytics API
• Usage and Cost API
• Admin API
• Compliance API 설정