GitHub Copilot의 크레딧 소비를 사용자 단위로 API 획득 가능: 모니터링을 자동화하는 ai_credits_used 사용법
요약
GitHub Copilot usage metrics API에 사용자별 크레딧 소비량을 나타내는 ai_credits_used 필드가 추가되었습니다. 이를 통해 기업은 사용자별 AI 크레딧 사용량을 프로그램으로 자동 모니터링하고 헤비 유저 식별 및 예산 관리를 효율적으로 수행할 수 있습니다.
핵심 포인트
- ai_credits_used 필드를 통한 사용자 단위 크레딧 소비 자동 모니터링 가능
- 헤비 유저 식별 및 소비 편중 현상의 가시화 자동화
- 사용자별 적정 예산(ULB) 설정을 위한 데이터 근거 확보
- 인게이지먼트 지표와 소비 데이터를 결합한 다각적 분석 가능
서론
GitHub Copilot의 종량제 과금(usage-based billing)에 대해서는 지금까지 두 편의 글을 써왔습니다.
첫 번째 글에서는 「AI credits」, 「풀링 (pooling)」, 「4단계 예산 제한」이라는 발표 시점의 사양을 정리하며, 마지막에 「향후 제공될 모니터링 도구를 활용하여 토큰 소비 경향을 파악하는 것이 핵심」이라고 적었습니다.
두 번째 글에서는 시행 후의 실태를 바탕으로, 「먼저 대시보드에서 실측한다」, 「헤비 유저를 특정한다」, 「주간·월간 사용량 리포트를 공유하여 소비의 편중을 가시화한다」를 실무 단계의 최우선 순위로 두었습니다.
요컨대 두 글 모두 「측정하라, 그리고 편중을 찾아내라」라고 말해온 것입니다.
하지만 그 "측정" 작업은 지금까지 대시보드를 육안으로 확인하거나, 리포트를 수동으로 집계하는 방법밖에 없었습니다.
2026년 6월 19일, 그 상황이 바뀌었습니다.
Copilot usage metrics API에 사용자별 소비 크레딧을 반환하는 ai_credits_used 필드가 추가된 것입니다. 이로써 「누가 얼마나 크레딧을 사용했는지」를 프로그램으로 가져올 수 있게 되었습니다.
본 기사는 이 새로운 필드로 무엇을 할 수 있게 되었는지, 그리고 모니터링에 사용할 때 반드시 파악해야 할 제약 사항을 지난 2편의 글의 맥락과 연결하여 정리한 속편입니다.
늘 그렇듯, 지난 글을 읽지 않은 분들도 이 글만으로 완결될 수 있도록 작성했습니다.
무엇이 추가되었는가
Copilot usage metrics API의 사용자 레벨 리포트에, 각 사용자가 해당 기간에 소비한 AI 크레딧의 총량을 나타내는 ai_credits_used 필드가 추가되었습니다.
값의 출처는 종량제 과금 (usage-based billing) API가 사용하는 것과 동일한 크레딧 소비 데이터입니다.
| 항목 | 내용 |
|---|---|
| 필드명 | ai_credits_used |
| ... | users-1-day (단일 일자) 및 users-28-day (28일) |
| 대상 레벨 | Enterprise / Organization 모두 |
| 데이터 출처 | 종량제 과금 API와 동일한 크레딧 소비 데이터 |
이 API는 최근에도 지속적으로 확장되고 있으며, 5월 말에는 사용자별 AI 활용 단계를 나타내는 ai_adoption_phase가 추가되었습니다.
GitHub가 사용자 레벨 리포트를 「채택도 + 소비」라는 양면에서 측정할 수 있는 방향으로 키워나가고 있음을 알 수 있습니다.
이것이 왜 효과적인가: 지난 숙제를 해결할 수 있다
이전 두 글에서 "하라"고 권했던 사항의 대부분을 이 필드로 자동화할 수 있습니다.
헤비 유저 특정이 한 번에 가능해짐: 「Chat · 에이전트 · cloud agent · 대규모 컨텍스트 이용이 많은 계층을 찾는다」라고 적었지만, ai_credits_used로 사용자를 정렬하면 소비 상위 사용자가 그대로 나타납니다 -
소비 편중의 가시화 자동화 가능: 「주간 · 월간 사용량을 공유하여 편중을 가시화한다」를 수동 집계가 아닌 정기 배치(batch)로 돌릴 수 있습니다 -
사용자 예산 (ULB) 설정의 근거 데이터를 얻을 수 있음: 두 번째 글에서 「사용자 예산만이 풀링 단계에서도 작동하는 유일한 하드 스톱(hard stop)」이라고 적었습니다. 누구에게 얼마만큼의 예산을 할당해야 할지, 그 적정선을 실제 소비 데이터로부터 결정할 수 있습니다 -
소비를 "가치"와 연결하여 볼 수 있음: 이 필드는 이미 추적 중인 인게이지먼트 (engagement) 지표와 동일한 리포트에 함께 존재합니다. 「어떤 작업이 그 소비를 발생시켰는가」를 소비 옆에 두고 볼 수 있는 설계입니다.
예산 제어가 「한도를 초과하면 멈추는 제어 (control)」라면, 이 필드는 「누가 얼마나 쓰고, 누가 한도에 가까워지고 있는지를 파악하는 관측 (observability)」입니다. 두 번째 글에서 강조한 제어와 본 기사의 관측. 이 두 바퀴가 갖춰져야 비로소 종량제 과금 운용이 돌아가기 시작합니다.
모니터링에 사용하기 전에 파악해야 할 4가지 함정
이 부분이 이 시리즈의 관례적인 "급소"입니다. 편리한 필드이지만, 성질을 오해하면 숫자를 잘못 읽게 됩니다.
| 급소 | 요점 |
|---|---|
| ① 내역은 가져올 수 없음 | feature / model / surface 별이 아닌, 사용자 단위의 총계만 |
| ... |
급소 1: feature · model · surface별 내역은 가져올 수 없음
ai_credits_used는 어디까지나 사용자 단위의 총계입니다.
GitHub 스스로가 「feature, model, surface별로는 분해되지 않는다」라고 명시하고 있습니다.
즉 「이 사용자가 Chat에서 몇 크레딧, 에이전트(Agent)에서 몇 크레딧, 어떤 모델에서 몇 크레딧을 사용했는지」와 같은 배분은 이 필드로는 불가능합니다.
기능별·모델별 비용 분석을 하고 싶다면, 다른 수단(모델별 소비는 대시보드, 로우 데이터(Raw data)는 NDJSON 내보내기, 명세는 billing 측 등)을 병용해야 합니다.
핵심 2: 이것은 「청구 금액」이 아니라 분석용 메트릭(Metrics) 시그널입니다
두 번째 글에서 「엔터프라이즈 예산은 총액의 상한선이 아니다」라고 썼던 것과 같은 종류의 주의사항입니다.
ai_credits_used
는 소비를 분석하기 위한 메트릭(Metrics)이지, 청구되는 금액 그 자체가 아닙니다. GitHub도 「invoicing은 billing을 참조하라」고 명시하고 있습니다.
사내 비용 보고에 사용한다면, 「이 숫자는 소비 경향 파악용이며, 확정 청구 금액은 billing 측이 정답이다」라는 단서를 반드시 덧붙여야 합니다. 메트릭(Metrics)과 청구를 혼동하면 경리 부서와의 조정 과정에서 차이가 발생할 수 있습니다.
핵심 3: 데이터에는 최대 2영업일의 지연(Lag)이 있다 (실시간 모니터링은 불가능)
이것은 모니터링을 설계할 때 결정적으로 중요합니다. Copilot usage metrics 데이터는 특정 날의 데이터가 「그날이 끝나고 UTC 기준으로 최대 2일 뒤」에 처리 및 반영됩니다.
따라서 이 API는 「지금 이 순간 누군가가 할당량을 다 써버리는 것을 감지하여 즉시 차단하는」 용도로는 사용할 수 없습니다. 실시간 하드 스톱(Hard stop)은 예산 제어(사용자 예산은 항상 하드 스톱)의 역할이며, 이 API는 며칠 늦은 트렌드 파악 및 사후 분석의 역할입니다. 역할을 혼동하지 마십시오.
핵심 4: 획득에는 관리자 권한과 정책 활성화가 필요하다
이 메트릭(Metrics)을 획득할 수 있는 사람은 Copilot usage metrics에 접근할 수 있는 엔터프라이즈 관리자, 조직 소유자(및 그에 상응하는 세분화된(Fine-grained) 권한을 가진 사용자)입니다.
전제로 「Copilot usage metrics」 정책이 활성화되어 있어야 합니다.
참고로, 이 API 그룹은 현재 퍼블릭 프리뷰(Public preview) 상태이며, 사양이 변경될 수 있다는 점에 유의하십시오.
구현 이미지: 리포트를 획득하여 ai_credits_used를 읽기
이 API는 「메트릭(Metrics)을 직접 반환」하는 것이 아니라, 「리포트 파일(JSON)의 다운로드 링크를 반환」하는 2단계 구조입니다. 절차는 다음과 같습니다.
- 사용자 레벨 리포트 엔드포인트를 호출하여
download_links와 대상 기간을 받는다. - 반환된 서명된 URL(Signed URL)로부터 리포트 JSON을 다운로드한다.
- 리포트 내의 각 사용자 레코드에서
ai_credits_used를 읽는다.
조직의 28일 리포트(users-28-day)를 획득하는 예시:
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
...
단일 날짜 데이터가 필요한 경우에는 users-1-day에 ?day=YYYY-MM-DD를 붙입니다. 엔터프라이즈 단위라면 /enterprises/ENTERPRISE/...로 변경합니다. API 버전은 이용 시점의 공식 문서를 확인하십시오.
응답은 리포트 본체가 아니라 서명된 다운로드 링크입니다 (단일 날짜 리포트는 대상일 report_day, 28일 리포트는 대상 기간이 반환됩니다):
{
"download_links": [
"https://example.com/copilot-usage-report-1.json"
...
이 링크의 JSON이 사용자 단위의 레코드이며, 각 레코드에 ai_credits_used가 포함됩니다 (아래는 구조의 이미지입니다. 실제 스키마는 공식 문서를 참조하십시오):
{
"user_login": "octocat",
"ai_credits_used": 142.5,
...
그 후 소비량으로 정렬하여 상위 사용자를 가려내거나, 임계값을 초과한 사용자를 Slack이나 Issue에 알림을 보내거나, 사용자 예산 재검토 큐에 넣는 등의 모니터링 흐름에 통합할 수 있습니다.
지연(Lag)이 있으므로, 용도는 「일간~주간 트렌드 감지 및 예산 튜닝」이 현실적입니다.
요약: 모니터링의 숙제에 공식적인 답이 나왔다
앞선 두 글의 결론에 본 기사의 업데이트를 더합니다.
- 지금까지 "측정하고, 편차를 찾아내라"라고 강조해 온 모니터링 작업이
ai_credits_used를 통해 프로그래밍화될 수 있게 되었다. 수동 집계에서 정기 배치 (Batch) 작업으로 전환이 가능하다. - 단, 이 필드는 ① 사용자 단위의 총계만 제공 (feature/model/surface별 내역 없음), ② 청구 금액이 아닌 분석용 메트릭 (Metrics), ③ 최대 2영업일의 지연 (Lag)이라는 세 가지 특성을 가진다. 이를 고려하지 않으면 수치를 오독할 수 있다. - 역할 분담을 고정한다. 예산 제어 (특히 사용자 예산)는 실시간 하드 스톱 (Hard stop)으로, 이 API는 며칠 늦은 관측용으로 사용한다. 제어와 관측을 두 바퀴로 하여 함께 돌려야 한다.
두 번째 기사에서 "이번 주 내로 사용자 예산 및 지출 상한의 정합성을 확인하라"고 기술했습니다. 본 기사를 추가한다면, 다음 단계는 "ai_credits_used를 정기적으로 가져와 소비 상위 항목과 트렌드를 시각화하는 체계를 마련하고, 그 실제 데이터를 사용자 예산 튜닝 (Tuning)에 활용하는 것"입니다. 제어만 하거나 관측만 하는 것은 반쪽짜리에 불과하며, 두 가지가 모두 갖춰져야 비로소 "상한을 높였는데 전사 서비스가 중단되는" 것과 같은 사고를 구조적으로 방지할 수 있습니다.
상황은 계속해서 유동적 (본 API도 퍼블릭 프리뷰 (Public Preview) 상태)이므로, Billing 대시보드와 더불어 usage metrics API의 변경 사항 (Changelog)도 정기 확인 대상에 포함해 두는 것을 권장합니다.
출처:
- AI credits consumed per user now in the Copilot usage metrics API - GitHub Changelog
- REST API endpoints for Copilot usage metrics - GitHub Docs
- GitHub Copilot usage metrics - GitHub Docs
- Copilot usage metrics API adds cohorts for AI adoption - GitHub Changelog
- Budgets for usage-based billing - GitHub Docs
Discussion
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기