Claude Enterprise Analytics API 참고 가이드

개요

Claude Enterprise Analytics API는 조직에 Claude 및 Claude Code 사용에 대한 참여 데이터에 대한 프로그래밍 방식의 액세스를 제공합니다. 사용자 활동을 위한 내부 대시보드를 구축하거나 프로젝트 채택을 추적하든, 이 API는 필요한 집계된 메트릭을 제공합니다.

데이터 집계

모든 데이터는 조직당, 일당 집계됩니다. 각 엔드포인트는 지정한 단일 날짜에 대한 스냅샷을 반환합니다. 날짜 (N-1)의 데이터는 날짜 N의 10:00:00 UTC 시간에 실행되며, 데이터 정확성을 보장하기 위해 집계 후 3일 후에 쿼리할 수 있습니다.

위의 타임라인 내에서 데이터를 사용할 수 없는 경우, 이는 일반적으로 당사 팀이 내부적으로 조사해야 하는 데이터 파이프라인 오류를 나타냅니다. 일반적으로 이러한 문제를 인식하고 있지만, 확인이 필요하거나 다른 문제가 의심되는 경우 CSM에 문의하시기 바랍니다.

액세스 활성화

새로운 분석 API 키를 생성하려면 Enterprise 조직 내에서 Primary Owner여야 합니다. claude.ai/analytics/api-keys로 이동하여 수행할 수 있습니다.

도움이 될 수 있는 추가 세부 정보:

언제든지 공개 API에 대한 액세스를 활성화/비활성화할 수 있습니다. 스위치를 끄면 모든 요청이 거부됩니다.
API에 액세스하려면 read:analytics 범위가 있는 키가 필요합니다. 조직에 대해 여러 키를 만들 수 있지만, 속도 제한은 키 수준이 아닌 조직 수준에서 적용됩니다. 아래의 "속도 제한" 섹션을 참조하세요.
항상 API 키를 안전하게 처리할 것을 강력히 권장합니다: 절대 이러한 키를 공개적으로 공유하지 마세요 - 이들은 비밀이며 안전하게 공유해야 합니다.

기본 URL

모든 요청은 다음으로 전송됩니다:

https://api.anthropic.com/v1/organizations/analytics/

인증

모든 요청에는 x-api-key 헤더에 전달된 API 키가 필요합니다. API 키에는 read:analytics 범위가 있어야 합니다. claude.ai 관리자 설정의 API 키 섹션에서 API 키를 만들고 관리할 수 있습니다.

요청 헤더 예시:

x-api-key: $YOUR_API_KEY

페이지 매김

여러 엔드포인트는 페이지가 매겨진 결과를 반환합니다. 페이지 매김은 커서 기반 접근 방식을 사용하며, 응답에는 다음 요청에서 다시 전달하여 다음 결과 페이지를 검색하는 next_page 토큰이 포함됩니다.

두 개의 선택적 매개변수가 페이지 매김을 제어합니다:

limit (정수): 페이지당 레코드 수입니다. /users 엔드포인트의 경우 기본값은 20이고 다른 모든 엔드포인트의 경우 100입니다. 최대값은 1000입니다.

page (문자열): 이전 응답의 next_page 필드의 불투명 커서 토큰입니다. 첫 번째 요청에서는 이를 생략하세요.

더 이상 결과가 없으면 응답에서 next_page는 null이 됩니다.

오류 응답

모든 엔드포인트는 표준 HTTP 오류 코드를 반환합니다:

코드	의미
400	쿼리 매개변수가 유효하지 않습니다. 일반적인 원인으로는 유효하지 않은 날짜, 1/1/26 이전의 날짜(첫 번째 가용성) 또는 오늘 또는 미래의 날짜가 있습니다. 데이터 가용성은 3일 지연됩니다.
404	API 키가 누락되었거나 유효하지 않거나 `read:analytics` 범위가 없습니다.
429	속도 제한 초과. 너무 많은 요청입니다.
503	일시적 오류, 다시 시도하세요.

속도 제한

기본 속도 제한이 있습니다. 사용 사례에 충분하지 않은 경우 이유를 알고 싶습니다. 필요한 경우 조직의 속도 제한을 조정할 수 있습니다. CSM에 문의하세요.

엔드포인트

1. 사용자 활동 나열

GET /v1/organizations/analytics/users

단일 날짜에 대한 사용자별 참여 메트릭을 반환합니다. 응답의 각 항목은 한 명의 사용자를 나타내며 Claude(채팅) 및 Claude Code 전체의 활동 수를 포함합니다.

쿼리 매개변수

필드	유형	필수	설명
`date`	문자열	예	메트릭을 검색할 날짜(YYYY-MM-DD 형식).
`limit`	정수	아니오	페이지당 레코드 수(기본값: 20, 최대: 1000).
`page`	문자열	아니오	이전 응답의 `next_page` 필드의 커서 토큰으로 다음 페이지를 검색합니다.

응답 필드(사용자당)

필드	설명
`user.id`	사용자의 고유 식별자.
`user.email_address`	사용자의 이메일 주소.
`chat_metrics.distinct_conversation_count`	Claude.ai 내에서의 고유 대화 수.
`chat_metrics.message_count`	Claude.ai 내에서 전송된 총 메시지 수.
`chat_metrics.distinct_projects_created_count`	Claude.ai 내에서 생성된 프로젝트 수.
`chat_metrics.distinct_projects_used_count`	Claude.ai 내에서 사용된 고유 프로젝트 수.
`chat_metrics.distinct_files_uploaded_count`	Claude.ai 내에서 업로드된 파일 수.
`chat_metrics.distinct_artifacts_created_count`	Claude.ai 내에서 생성된 아티팩트 수.
`chat_metrics.thinking_message_count`	Claude.ai 내에서의 사고(확장) 메시지 수.
`chat_metrics.distinct_skills_used_count`	Claude.ai 내에서 사용된 고유 스킬 수.
`chat_metrics.connectors_used_count`	Claude.ai 내에서 호출된 커넥터의 총 수.
`claude_code_metrics.core_metrics.commit_count`	Claude Code를 통해 생성된 git 커밋 수.
`claude_code_metrics.core_metrics.pull_request_count`	Claude Code를 통해 생성된 풀 요청 수.
`claude_code_metrics.core_metrics.lines_of_code.added_count`	추가된 총 코드 라인 수.
`claude_code_metrics.core_metrics.lines_of_code.removed_count`	제거된 총 코드 라인 수.
`claude_code_metrics.core_metrics.distinct_session_count`	고유 Claude Code 세션 수.
`claude_code_metrics.tool_actions.edit_tool`	Edit 도구의 수락 및 거부 수.
`claude_code_metrics.tool_actions.multi_edit_tool`	Multi-Edit 도구의 수락 및 거부 수.
`claude_code_metrics.tool_actions.write_tool`	Write 도구의 수락 및 거부 수.
`claude_code_metrics.tool_actions.notebook_edit_tool`	Notebook Edit 도구에 대한 수락 및 거부 횟수입니다.
`web_search_count`	웹 검색 도구 호출의 총 횟수입니다. 이는 claude.ai와 조직 내 Claude 코드 사용 모두에 적용됩니다.

Office Agent 메트릭(사용자당)

각 사용자 레코드에는 Excel 및 PowerPoint에 대한 제품별 분석을 포함하는 office_metrics 객체도 포함됩니다. 이 블록은 모든 레코드에 항상 존재하며, Office Agent를 사용하지 않는 조직은 null 대신 모든 값이 0으로 표시됩니다.

office_metrics 객체에는 excel과 powerpoint 두 개의 키가 포함됩니다.

각 키에는 동일한 6개의 필드가 포함됩니다:

필드	설명
`office_metrics.[product].distinct_session_count*`	고유한 Office Agent 세션의 수입니다.
`office_metrics.[product].message_count`	전송된 메시지의 수입니다(완료된 에이전트 턴당 하나).
`office_metrics.[product].skills_used_count`	총 스킬 호출 수입니다. 한 번에 5번 사용된 스킬은 5로 계산됩니다.
`office_metrics.[product].distinct_skills_used_count`	사용된 고유한 스킬의 수입니다.
`office_metrics.[product].connectors_used_count`	총 커넥터 호출 수입니다. 한 번에 3번 사용된 커넥터는 3으로 계산됩니다.
`office_metrics.[product].distinct_connectors_used_count`	사용된 고유한 커넥터의 수입니다.

*참고: [product]는 excel 또는 powerpoint 중 하나입니다.

요청 예시

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/users?date=2025-01-01&limit=3"
   --header "x-api-key: $YOUR_API_KEY"

2. 활동 요약

GET /v1/organizations/analytics/summaries

주어진 날짜 범위에 대해 조직의 참여도 및 좌석 사용률에 대한 일일 고수준 요약을 반환합니다. 응답은 날짜 범위 내의 집계된 횟수가 있는 날짜 목록입니다. ending_date와 starting_date 간의 최대 차이는 31일이어야 하며, 데이터 가용성에는 3일의 지연이 있습니다. 이는 일일 활성 사용자, 주간 및 월간 추세, 좌석 할당을 한눈에 추적하는 데 유용합니다.

"활성"의 정의 다음 중 하나라도 참이면:

사용자가 Claude(채팅)에서 최소 1개의 채팅 메시지를 보냈습니다.
사용자가 C4E 조직과 연결된 최소 1개의 Claude 코드(로컬 또는 원격) 세션을 가지고 있으며, 도구 사용/git 활동이 있습니다.

쿼리 매개변수

필드	유형	필수	설명
`starting_date`	문자열	예	데이터를 검색할 시작 날짜(YYYY-MM-DD 형식)입니다. 데이터 가용성에는 3일의 지연이 있으므로 액세스할 수 있는 가장 최근 데이터는 3일 전입니다.
`ending_date`	문자열	아니오	데이터를 검색할 선택적 종료 날짜(YYYY-MM-DD 형식)입니다. 이는 배타적입니다.

응답 필드

필드	설명
`starting_date`	메트릭이 집계된 첫 번째 날(UTC 날짜로 해석됨). 데이터 가용성에는 3일의 지연이 있으므로 액세스할 수 있는 가장 최근 데이터는 3일 전입니다.
`ending_date`	메트릭이 집계된 마지막 날(배타적, UTC 날짜로 해석됨)
`daily_active_user_count`	지정된 날짜에 활성 사용자 수(토큰 소비 기준).
`weekly_active_user_count`	지정된 날짜로 끝나는 7일 롤링 윈도우 내에서 활성 사용자 수.
`monthly_active_user_count`	지정된 날짜로 끝나는 30일 롤링 윈도우 내에서 활성 사용자 수.
`assigned_seat_count`	조직에서 현재 할당된 총 좌석 수.
`pending_invite_count`	아직 수락되지 않은 보류 중인 초대 수.

참고: 주간 및 월간 카운트의 롤링 윈도우는 지정된 날짜(포함)에서 역방향으로 봅니다. 윈도우 내 일부 날짜의 데이터가 불완전한 경우(예: 날짜가 과거 30일 미만인 경우), 월간 카운트가 활동을 과소 계산할 수 있습니다.

요청 예시

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/summaries?starting_date=2025-01-01"
   --header "x-api-key: $YOUR_API_KEY"

3. 채팅 프로젝트 사용량

GET /v1/organizations/analytics/apps/chat/projects

주어진 날짜에 대해 채팅 프로젝트별로 분류된 사용량 데이터를 반환합니다. 프로젝트는 Claude(채팅)에 특정되므로 이 엔드포인트는 해당 표면에 중점을 둡니다. 각 항목은 프로젝트 이름, 상호작용한 고유 사용자 수, 해당 프로젝트에서 진행된 총 대화 수를 표시합니다.

쿼리 매개변수

필드	유형	필수	설명
`date`	문자열	예	YYYY-MM-DD 형식의 메트릭을 검색할 날짜입니다. 데이터 가용성에 3일의 지연이 있으므로 액세스할 수 있는 가장 최근 데이터는 3일 전의 데이터입니다.
`limit`	정수	아니오	페이지당 레코드 수(기본값: 100, 최대: 1000).
`page`	문자열	아니오	다음 페이지를 검색하기 위해 이전 응답의 `next_page` 필드의 커서 토큰입니다.

응답 필드(프로젝트당)

필드	설명
`project_name`	프로젝트의 이름입니다.
`project_id`	태그된 프로젝트 ID(예: "claude_proj_{ID}")
`distinct_user_count`	주어진 날짜에 이 프로젝트를 사용한 고유 사용자 수입니다.
`distinct_conversation_count`	주어진 날짜에 이 프로젝트의 대화 수입니다.
`message_count`	주어진 날짜에 이 프로젝트 내에서 전송된 총 메시지 수입니다.
`created_at`	프로젝트 생성 타임스탬프입니다.
`created_by`	프로젝트를 생성한 사용자의 `{id, email_address}`입니다.

요청 예시

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/apps/chat/projects?date=2025-01-01&limit=50"
   --header "x-api-key: $YOUR_API_KEY"

4. 스킬 사용

GET /v1/organizations/analytics/skills

조직 내에서 Claude(채팅)와 Claude Code 모두에서 주어진 날짜에 대한 스킬 사용 데이터를 반환합니다. 각 항목은 스킬을 나타내며 고유 사용자가 몇 명 사용했는지 보여줍니다.

쿼리 매개변수

필드	유형	필수	설명
`date`	문자열	예	YYYY-MM-DD 형식의 메트릭을 검색할 날짜입니다. 데이터 가용성에 3일의 지연이 있으므로 액세스할 수 있는 가장 최근 데이터는 3일 전입니다.
`limit`	정수	아니요	페이지당 레코드 수(기본값: 100, 최대: 1000).
`page`	문자열	아니요	다음 페이지를 검색하기 위해 이전 응답의 `next_page` 필드의 커서 토큰입니다.

응답 필드(스킬당)

필드	설명
`skill_name`	스킬의 이름입니다.
`distinct_user_count`	주어진 날짜에 이 스킬을 사용한 고유 사용자의 수입니다.
`chat_metrics.distinct_conversation_skill_used_count`	채팅에서 스킬이 최소 한 번 이상 사용된 고유 대화의 수입니다.
`claude_code_metrics.distinct_session_skill_used_count`	Claude Code에서 스킬이 최소 한 번 이상 사용된 고유 원격 세션의 수입니다.

Office Agent 메트릭(스킬당)

각 스킬 레코드에는 Office Agent 세션이 스킬을 사용한 횟수를 제품별로 분류하여 보고하는 office_metrics 객체도 포함됩니다. 이 블록은 항상 존재하며, Office Agent 사용이 없는 조직은 모두 0 값을 표시합니다.

필드	설명
`office_metrics.excel.distinct_session_skill_used_count`	이 스킬이 사용된 Excel의 고유 Office Agent 세션 수입니다.
`office_metrics.powerpoint.distinct_session_skill_used_count`	이 스킬이 사용된 PowerPoint의 고유 Office Agent 세션 수입니다.

요청 예시

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/skills?date=2025-01-01"
   --header "x-api-key: $YOUR_API_KEY"

5. 커넥터 사용

GET /v1/organizations/analytics/connectors

조직 내에서 Claude(채팅)와 Claude Code 모두에서 주어진 날짜에 대한 MCP/커넥터 사용 데이터를 반환합니다. 각 항목은 커넥터를 나타내며 고유 사용자가 몇 명 사용했는지 보여줍니다. 커넥터 이름은 다양한 소스에서 정규화됩니다. 예를 들어 "Atlassian MCP server," "mcp-atlassian," "atlassian_MCP"는 모두 "atlassian"으로 표시됩니다.

쿼리 매개변수

필드	유형	필수	설명
`date`	문자열	예	메트릭을 검색할 날짜(YYYY-MM-DD 형식). 데이터 가용성에 3일의 지연이 있으므로 액세스할 수 있는 가장 최근 데이터는 3일 전의 데이터입니다.
`limit`	정수	아니요	페이지당 레코드 수(기본값: 100, 최대: 1000).
`page`	문자열	아니요	이전 응답의 `next_page` 필드의 커서 토큰으로 다음 페이지를 검색합니다.

응답 필드(커넥터별)

필드	설명
`connector_name`	커넥터의 정규화된 이름입니다.
`distinct_user_count`	주어진 날짜에 이 커넥터를 사용한 고유 사용자의 수입니다.
`chat_metrics.distinct_conversation_connector_used_count`	채팅에서 커넥터가 최소 한 번 이상 사용된 고유 대화의 수입니다.
`claude_code_metrics.distinct_session_connector_used_count`	Claude Code에서 스킬이 최소 한 번 이상 사용된 고유 원격 세션의 수입니다.

Office Agent 메트릭(커넥터별)

각 커넥터 레코드에는 Office Agent 세션이 커넥터를 사용한 횟수를 제품별로 분류하여 보고하는 office_metrics 객체도 포함됩니다. 이 블록은 항상 존재하며, Office Agent 사용이 없는 조직은 모든 값이 0으로 표시됩니다.

필드	설명
`office_metrics.excel.distinct_session_connector_used_count`	이 커넥터가 사용된 Excel의 고유 Office Agent 세션 수입니다.
`office_metrics.powerpoint.distinct_session_connector_used_count`	이 커넥터가 사용된 PowerPoint의 고유 Office Agent 세션 수입니다.

요청 예시

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/connectors?date=2025-01-01"
   --header "x-api-key: $YOUR_API_KEY"