데이터 조회 API
관리자 화면 데이터 메뉴가 보여주는 지표를 API 키 인증으로 그대로 가져오는 읽기 전용 API입니다. 고객사 포털이나 사내 대시보드가 서버에서 직접 호출해 원하는 형태로 다시 그리는 용도입니다.
관리자 화면과 이 API는 같은 집계 함수를 부릅니다. 화면에 보이는 숫자와 API가 돌려주는 숫자가 갈라지지 않습니다.
- Base Path:
/v1/data - Host:
https://factchat-cloud.mindlogic.ai(API Gateway와 같은 호스트입니다. 조직 서비스 도메인*.factchat.bot이 아닙니다) - 인증: API 키 (
Authorization: Bearer YOUR_API_KEY) - 메서드: 전부
GET. 쓰기 동작은 없습니다 - 사용 전 기능 활성화 요청이 필요합니다 (아래 사전 준비 참고)
사전 준비
1. 기능 활성화 요청
이 API는 조직 단위로 꺼진 상태가 기본입니다. 관리자 화면에는 켜는 설정이 없으므로 마인드로직 담당자에게 활성화를 요청해주세요. 활성화 전에 호출하면 모든 요청이
403입니다.2. API 키 준비
이미 쓰고 있는 FactChat API 키를 그대로 씁니다. 모델 호출용 키와 같은 키이고, 따로 발급받을 필요가 없습니다. 발급 절차는 API Gateway 인증과 API 키 관리를 참고하세요.
키 소유자는 활성 상태의 전체 관리자여야 합니다. 일반 구성원, 그룹 관리자, 사용이 중지된
계정의 키로 호출하면
403입니다. 그룹 관리자 키는 사용할 수 없습니다.인증
Authorization 헤더가 권장이고, x-api-key 헤더도 같은 값을 받습니다.어느 조직의 데이터가 나가는지는 API 키가 결정합니다. 서버가 키에 묶인 소유자의 조직을 직접 찾으므로 호스트는 위 하나뿐이고, 조직별 주소를 쓰지 않습니다. 다른 조직의 키로는 그 조직의 데이터만 나옵니다.
브라우저 관리자 화면(
/v1/admin/*, 세션 쿠키 인증)과는 경로가 분리돼 있습니다. 관리자 화면 주소에 API 키를 넣어도 통하지 않고, 반대도 마찬가지입니다.경로 끝의 슬래시(
/)는 생략할 수 없습니다. /v1/data/usage처럼 보내면 404입니다.엔드포인트 한눈에 보기
| 엔드포인트 | 돌려주는 것 | 관리자 화면 |
|---|---|---|
GET /v1/data/usage/ | 조직 전체의 모델별·기능별 크레딧 사용량 | 크레딧 사용량 |
GET /v1/data/usage/group/ | 같은 값을 멤버 그룹 단위로 | 크레딧 사용량 |
GET /v1/data/credits/ | 크레딧 구매 내역 | 크레딧 구매 내역 |
GET /v1/data/user-activity/ | DAU·방문자 수 시계열 | 사용자 활동 |
GET /v1/data/model-analytics/ | 모델 통계 요약과 시계열 | 모델별 통계 |
GET /v1/data/model-analytics/models/ | 필터에 넣을 모델 목록 | 모델별 통계 |
GET /v1/data/conversation-keywords/ | 대화 분석 키워드와 대화 수 | 대화 분석 |
GET /v1/data/conversation-analysis/status/ | 대화 분석 기능 상태와 비용 프리뷰 | 대화 분석 |
마지막 두 개는 조직에 대화 분석 기능이 켜져 있어야 합니다. 꺼져 있으면 그 두 개만
403이고 나머지 여섯 개는 그대로 동작합니다.크레딧 사용량
GET
/v1/data/usage/조직 전체의 크레딧 사용량을 모델별·기능별로 합산해 돌려줍니다.
파라미터
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
start_date / end_date | YYYY-MM-DD | N | 이번 달 1일 ~ 오늘 | 둘 다 주면 이 구간을 씁니다 |
start_month / end_month | YYYY-MM | N | — | start_date·end_date가 없을 때만 적용되는 월 단위 구간 |
usage_source | all | apikey | console | N | all | 사용 경로 필터 |
credit_source | all | organization | personal | N | all | 크레딧 출처 필터 |
응답 예시
total_credit은 과금된 사용분만 더합니다. 무료 사용분은 크레딧에 잡히지 않지만 토큰 수에는
들어갑니다. 정산 기준과 활동 지표의 의도된 차이입니다.크레딧 사용량 (그룹별)
GET
/v1/data/usage/group/같은 집계를 멤버 그룹 단위로 좁혀 돌려줍니다. 응답 모양은 위와 같습니다.
파라미터
크레딧 사용량의 파라미터를 모두 그대로 쓰고, 아래가 더해집니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
member_group_id | int | 조건부 | — | 조회할 그룹. 0이면 해당 타입의 미분류 멤버 |
intersection_group_id | int | 조건부 | — | 교차 그룹으로 조회 |
member_group_type_id | int | N | — | member_group_id=0일 때 대상 그룹 유형 지정 |
filter_type | quota_source | group_members | N | quota_source | 크레딧 귀속 기준으로 셀지, 그룹 소속 멤버 기준으로 셀지 |
member_group_id와 intersection_group_id 중 하나는 반드시 있어야 합니다. 둘 다 없으면 400입니다.여기서 쓰는 그룹 id는 정수입니다. 관리자 화면의 그룹 관리에서 사이드바의 그룹을 선택하면 주소창이
/admin/group-management?type=group&id=42&groupTypeId=1 처럼 바뀌는데, 이 값이 그대로 파라미터가 됩니다.| 주소창 | 파라미터 |
|---|---|
type=group 일 때의 id | member_group_id |
type=intersection 일 때의 id | intersection_group_id |
groupTypeId | member_group_type_id |
멤버 그룹 관리 API의 스키마 조회가 돌려주는 id는
"a91c..." 같은 문자열이라 이 API에는 쓸 수 없습니다. 그대로 넣으면 그룹이 선택되는 대신
검증에서 걸립니다. 두 API는 서로 다른 식별자 체계를 씁니다.크레딧 구매 내역
GET
/v1/data/credits/조직에 지급·충전된 크레딧을 건별로 돌려줍니다.
파라미터
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
page | int | N | 1 | 페이지 번호 |
size | int | N | 10 | 한 페이지 건수. 최대 1000 |
order_by | string | N | created_at.desc | created_at·usage_start_date·usage_end_date 뒤에 .asc 또는 .desc |
is_depleted | bool | N | — | 소진 여부 필터 |
is_expired | bool | N | — | 만료 여부 필터 |
응답 예시
order_by가 허용 목록 밖이면 400입니다. 기본 정렬로 조용히 돌아가지 않으니 오타를 응답으로
확인할 수 있습니다.사용자 활동
GET
/v1/data/user-activity/DAU와 방문자 수를 시계열로 돌려줍니다. 하루 단위 배치 결과라 당일 데이터는 아직 없을 수 있습니다.
파라미터
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
start_date / end_date | YYYY-MM-DD | N | 오늘 포함 최근 30일 | |
interval | day | week | month | N | day | 데이터포인트 간격 |
member_group_id | int | N | — | 그룹 필터 |
응답 예시
개인 식별 정보가 나가지 않습니다. 사람 수만 돌려주며 멤버 목록이나 이메일은 포함하지
않습니다.
모델별 통계
GET
/v1/data/model-analytics/모델 카테고리별 요청 수·토큰·크레딧·응답 속도를 요약과 시계열로 돌려줍니다. 하루 단위 배치 결과이고, 응답의
last_aggregated_at이 집계 기준 시각입니다.파라미터
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
start_date / end_date | YYYY-MM-DD | Y | start_date는 집계 시작일인 2025-03-01 이후여야 합니다 |
interval | day | week | month | Y | |
model_category | 아래 목록 중 하나 | N | 없으면 전체 카테고리 |
model_ids | 1,2,3 | N | 지정하면 모델별 breakdown이 붙습니다. model_category와 함께 보내야 합니다 |
model_category에 넣을 수 있는 값: llm, image, video, voice, korea_in_data, univ_in_data, law_in_data, deep_research, ppt, hwp, super_agent.응답 예시
집계 결과가 없는 구간은 배열에서 빠지지 않고 지표 필드가
null인 상태로 들어옵니다. 그래프를 그릴 때 0으로 바꿔 넣을지 선을 끊을지는 받는 쪽에서 정하시면 됩니다.모델 목록
GET
/v1/data/model-analytics/models/모델별 통계의
model_ids에 넣을 값을 조회합니다.파라미터
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
model_category | 모델별 통계와 같은 목록 | Y | 빠지면 422 |
응답 예시
대화 분석 — 키워드
GET
/v1/data/conversation-keywords/대화에서 뽑아낸 키워드와 그 키워드가 나온 대화 수를 돌려줍니다. 조직에 대화 분석 기능이 켜져 있어야 하고, 꺼져 있으면
403입니다.파라미터
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
start_date / end_date | YYYY-MM-DD | N | 최근 30일 | 대화 첫 메시지 시각 기준, 양끝 포함 |
chatbot_id | int | N | — | 챗봇 필터 |
page | int | N | 1 | 페이지 번호 |
size | int | N | 50 | 한 페이지 건수. 최대 100 |
응답 예시
대화 본문은 나가지 않습니다. 정규화된 키워드 라벨과 대화 수만 돌려줍니다.
대화 분석 — 상태
GET
/v1/data/conversation-analysis/status/대화 분석 기능이 켜져 있는지, 최근 실행이 언제였는지, 크레딧이 얼마나 드는지를 돌려줍니다. 파라미터는 없습니다. 키워드 조회와 같은 활성화 조건이 걸립니다.
응답 예시
관리자 화면에는 이 기능을 켜고 끄는 토글이 있지만, API로는 상태를 읽기만 합니다. 토글은 관리자 화면에서 조작해주세요.
에러 코드
| 코드 | 언제 | 본문 형태 |
|---|---|---|
400 | 파라미터 값의 의미가 어긋남 — start_date가 end_date보다 늦음, 날짜 형식 오류, 허용 목록 밖의 order_by, 그룹 id 누락, 모델 통계의 start_date가 2025-03-01 이전, model_category 없이 보낸 model_ids | 객체 |
401 | 키 누락, 잘못된 키, 사용이 중지된 키 | 객체 |
403 | 조직에 이 API가 활성화돼 있지 않음, 키 소유자가 관리자가 아니거나 비활성 계정, 대화 분석이 꺼진 상태에서 대화 분석 2종 호출 | 객체 |
404 | 존재하지 않는 경로 — 끝 슬래시 누락, 지원하지 않는 경로 | 객체 |
405 | 허용되지 않는 메서드. 이 API는 GET만 받습니다 | 객체 |
422 | 파라미터 자체가 규격을 어김 — 열거형에 없는 값(usage_source·credit_source·interval·model_category), 상한을 넘는 size, 필수 파라미터 누락 | 배열 |
503 | 조직이 점검 중 | 객체 |
본문이 두 가지인 이유
의미 검증에서 걸린 요청과 형식 검증에서 걸린 요청은
detail의 모양이 다릅니다. 파싱하는 쪽에서 둘 다 처리해주세요.400·401·403·503 — detail이 문자열입니다.422 — FastAPI의 요청 검증 응답이라 detail이 배열입니다.간단히 구분하려면
detail이 배열인지 먼저 보고, 배열이면 각 항목의 loc에서 문제가 된 파라미터 이름을 꺼내면 됩니다.다음 단계
- API 키 관리 — 조직에 발급된 키와 소유자 확인
- API Gateway 인증 — 키 발급 방법
- 멤버 그룹 관리 API — 그룹·구성원 동기화 API
- 크레딧 사용량 — 같은 지표의 관리자 화면
마지막 수정 날짜: Aug 31, 2026