> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 일별 청구서 조회

> 날짜별 청구서 소비 상세 및 일 요약 데이터를 조회하여 정산, 비용 분석, 청구서 수집에 사용

<Info>
  날짜별로 청구서의 **소비 상세**와 **일 요약** 데이터를 조회하여 클라이언트 측 정산, 비용 분석, 청구서 수집에 사용합니다.
</Info>

## 엔드포인트 정보

| 항목      | 설명                                  |
| ------- | ----------------------------------- |
| 서비스 도메인 | `https://maas.gravitex.ai/prod-api` |
| 데이터 형식  | `application/json`                  |
| 문자 인코딩  | `UTF-8`                             |
| 프로토콜    | `HTTPS` (필수)                        |
| 금액 통화   | `USD` (달러)                          |
| 과금 시간대  | `utc+8`                             |

### 엔드포인트 목록

| 엔드포인트 | 요청 주소                           | 용도                                         |
| ----- | ------------------------------- | ------------------------------------------ |
| 소비 상세 | `GET /api/logs/getDailyList`    | `(청구일 × 계정 × 모델 × Token 유형)` 기준으로 소비 상세 반환 |
| 일 요약  | `GET /api/logs/getDailySummary` | `(청구일 × 계정)` 기준으로 당일 소비 순액 요약 반환           |

## 인증

모든 요청은 HTTP Header에 Bearer 자격 증명을 포함해야 합니다. **다음 두 가지 자격 증명 중 하나를 선택**할 수 있습니다:

| 자격 증명 유형                                                              | 설명                                 |
| --------------------------------------------------------------------- | ---------------------------------- |
| [액세스 토큰 (Access Token)](https://maas.gravitex.ai/#/profile?tab=token) | 플랫폼이 계정에 할당한 액세스 토큰                |
| [API 키 (API Key)](/cn/interface-module/token-management)              | 플랫폼이 계정용으로 생성한 API 키, 보통 `sk-`로 시작 |

<ParamField header="Authorization" type="string" required>
  형식 `Bearer <자격증명>`; 위 자격 증명 중 하나를 입력
</ParamField>

```http theme={null}
# 방식 1: 액세스 토큰
Authorization: Bearer <access_token>

# 방식 2: API 키
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
```

인증 실패 시 HTTP `401`, 비즈니스 코드 `40100`을 반환합니다.

<Warning>
  URL, 프론트엔드 코드, 로그, 지원 티켓에 전체 키를 기록하지 마세요.
</Warning>

## 공통 응답 구조

모든 엔드포인트는 통일된 구조를 반환합니다:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 128,
    "rows": []
  }
}
```

| 필드           | 유형      | 설명                             |
| ------------ | ------- | ------------------------------ |
| `code`       | integer | 비즈니스 상태 코드, `0`은 성공, 비 `0`은 실패 |
| `message`    | string  | 안내 메시지                         |
| `data`       | object  | 비즈니스 데이터 본문; 실패 시 `null`       |
| `data.total` | integer | 조회 조건을 만족하는 총 건수 (페이지네이션용)     |
| `data.rows`  | array   | 데이터 행 목록                       |

### 비즈니스 오류 코드

| code  | HTTP 상태 | 설명                                                  |
| ----- | ------- | --------------------------------------------------- |
| 0     | 200     | 성공                                                  |
| 40001 | 400     | 파라미터 형식 오류 (날짜 형식 오류, 페이지네이션 파라미터가 양의 정수가 아님 등)     |
| 40002 | 400     | 필수 파라미터 누락                                          |
| 40003 | 400     | 날짜 구간 오류 (`startDate`가 `endDate`보다 늦거나, 기간이 상한을 초과) |
| 40100 | 401     | Token 누락, 무효 또는 만료                                  |
| 50000 | 500     | 서버 내부 오류                                            |

***

## 소비 상세 조회

```
GET https://maas.gravitex.ai/prod-api/api/logs/getDailyList
```

`(청구일 × 계정 × 모델 × Token 유형)` 기준으로 소비 상세를 반환합니다.

### 쿼리 파라미터

<ParamField query="startDate" type="string" required>
  시작 날짜, 형식 `yyyy-MM-dd`
</ParamField>

<ParamField query="endDate" type="string" required>
  종료 날짜, 형식 `yyyy-MM-dd`; `startDate`와의 기간은 **92일**을 초과할 수 없음
</ParamField>

<ParamField query="userId" type="string">
  계정 ID 필터 (다중 하위 계정 조회에는 「기업 관리」 개통 필요, [비즈니스 규칙](#비즈니스-규칙과-약정) 참고); 미전달 시 현재 자격 증명으로 볼 수 있는 계정 반환
</ParamField>

<ParamField query="userName" type="string">
  계정명 필터, 정확 일치 (다중 하위 계정 조회에는 「기업 관리」 개통 필요, [비즈니스 규칙](#비즈니스-규칙과-약정) 참고); 미전달 시 현재 자격 증명으로 볼 수 있는 계정 반환
</ParamField>

<ParamField query="pageSize" type="string" required>
  페이지 크기, 양의 정수 문자열; 범위 `1 ~ 100`, 100 초과 시 100으로 처리
</ParamField>

<ParamField query="pageNum" type="string" required>
  현재 페이지 번호, 양의 정수 문자열, `1`부터 시작
</ParamField>

<Note>
  페이지네이션 단위는 「소비 상세 항목」이며, `data.total`은 조건을 만족하는 상세 총 건수입니다.
</Note>

### 응답 행 필드 (`data.rows[]`)

| 필드                      | 유형     | 설명                                                                                                                                           |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `billMonth`             | string | 청구 월, 형식 `yyyyMM`                                                                                                                            |
| `billDay`               | string | 청구일, 형식 `yyyy-MM-dd`                                                                                                                         |
| `billingDateTimezone`   | string | 과금 시간대, 고정 `utc+8`                                                                                                                           |
| `account`               | string | 계정명                                                                                                                                          |
| `modelType`             | string | 모델 분류, 예: `claude`, `gpt`, `gemini`, `qwen`, `deepseek` 등                                                                                    |
| `modelName`             | string | 모델 이름                                                                                                                                        |
| `tokenType`             | string | Token 유형, 아래 enum 참고                                                                                                                         |
| `tokenCount`            | string | 해당 유형의 소비 Token 수 (문자열형 정수)                                                                                                                  |
| `tokenUnit`             | string | Token 계량 단위, 고정 `million` (백만 Token당 과금)                                                                                                     |
| `currency`              | string | 통화 유형, 고정 `USD`                                                                                                                              |
| `subtotalBeforeTax`     | string | 할인 전 세전 금액 (소수점 8자리)                                                                                                                         |
| `subtotalAfterDiscount` | string | 할인 후 세전 금액 (소수점 8자리)                                                                                                                         |
| `totalAmountAfterTax`   | string | 할인 후 세후 금액 (소수점 8자리)                                                                                                                         |
| `price`                 | string | 단가: **`tokenUnit` 1개(즉 백만 Token)** 당 할인 전 단가 (소수점 8자리). 환산: `subtotalBeforeTax = price × tokenCount ÷ 1,000,000`; `tokenCount`가 0이면 생략될 수 있음 |
| `entryType`             | string | 항목 유형, `normal`은 정상 소비                                                                                                                       |

### `tokenType` enum

| 열거값                     | 설명                    |
| ----------------------- | --------------------- |
| `textInputTokens`       | 텍스트 입력 Token          |
| `textOutputTokens`      | 텍스트 출력 Token          |
| `reasoningTokens`       | 추론/사고 Token           |
| `cacheCreationTokens5m` | 캐시 생성 Token (5분 TTL)  |
| `cacheCreationTokens1h` | 캐시 생성 Token (1시간 TTL) |
| `cacheTokens`           | 캐시 히트(읽기) Token       |
| `imageInputTokens`      | 이미지 입력 Token          |
| `imageOutputTokens`     | 이미지 출력 Token          |
| `audioInputTokens`      | 오디오 입력 Token          |
| `audioOutputTokens`     | 오디오 출력 Token          |
| `videoInputTokens`      | 비디오 입력 Token          |
| `videoOutputTokens`     | 비디오 출력 Token          |

<Note>
  정렬 규칙: `billDay` 내림차순, 이어서 `account`, `modelName`, `tokenType`, `currency` 오름차순.
</Note>

### 요청 예시

```bash theme={null}
curl "https://maas.gravitex.ai/prod-api/api/logs/getDailyList?startDate=2026-07-27&endDate=2026-07-27&pageSize=100&pageNum=1" \
  -H "Authorization: Bearer <your_token>"
```

### 응답 예시

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 23,
    "rows": [
      {
        "billMonth": "202607",
        "billDay": "2026-07-27",
        "billingDateTimezone": "utc+8",
        "account": "your_account",
        "modelType": "claude",
        "modelName": "claude-opus-4-8",
        "tokenType": "textOutputTokens",
        "tokenCount": "2931",
        "tokenUnit": "million",
        "currency": "USD",
        "subtotalBeforeTax": "0.07327564",
        "subtotalAfterDiscount": "0.07327564",
        "totalAmountAfterTax": "0.07327564",
        "price": "25.00021836",
        "entryType": "normal"
      }
    ]
  }
}
```

***

## 일 요약 조회

```
GET https://maas.gravitex.ai/prod-api/api/logs/getDailySummary
```

일 단위 소비 순액 요약을 반환합니다. 상세 엔드포인트보다 응답이 가볍고, 청구서 개요, 일별 추이, 월간 리포트 등에 적합합니다.

### 쿼리 파라미터

<ParamField query="startDate" type="string" required>
  시작 날짜, 형식 `yyyy-MM-dd`
</ParamField>

<ParamField query="endDate" type="string" required>
  종료 날짜, 형식 `yyyy-MM-dd`; `startDate`와의 기간은 **366일**을 초과할 수 없음
</ParamField>

<ParamField query="userId" type="string">
  계정 ID 필터 (다중 하위 계정 조회에는 「기업 관리」 개통 필요, [비즈니스 규칙](#비즈니스-규칙과-약정) 참고); 미전달 시 현재 자격 증명으로 볼 수 있는 계정 반환
</ParamField>

<ParamField query="userName" type="string">
  계정명 필터, 정확 일치 (다중 하위 계정 조회에는 「기업 관리」 개통 필요, [비즈니스 규칙](#비즈니스-규칙과-약정) 참고); 미전달 시 현재 자격 증명으로 볼 수 있는 계정 반환
</ParamField>

<ParamField query="pageSize" type="string" required>
  페이지 크기, 양의 정수 문자열; 범위 `1 ~ 400`, 400 초과 시 400으로 처리
</ParamField>

<ParamField query="pageNum" type="string" required>
  현재 페이지 번호, 양의 정수 문자열, `1`부터 시작
</ParamField>

<Note>
  페이지네이션 단위는 「청구일 × 계정」이며, `data.total`은 조건을 만족하는 조합 총수입니다.
</Note>

### 응답 행 필드 (`data.rows[]`)

| 필드                      | 유형     | 설명                      |
| ----------------------- | ------ | ----------------------- |
| `billMonth`             | string | 청구 월, 형식 `yyyyMM`       |
| `billDay`               | string | 청구일, 형식 `yyyy-MM-dd`    |
| `billingDateTimezone`   | string | 과금 시간대, 고정 `utc+8`      |
| `account`               | string | 계정명                     |
| `currency`              | string | 통화 유형, 고정 `USD`         |
| `subtotalBeforeTax`     | string | 당일 할인 전 세전 순액 (소수점 8자리) |
| `subtotalAfterDiscount` | string | 당일 할인 후 세전 순액 (소수점 8자리) |
| `totalAmountAfterTax`   | string | 당일 할인 후 세후 순액 (소수점 8자리) |

<Note>
  정렬 규칙: `billDay` 내림차순, 이어서 `account` 오름차순.
</Note>

### 요청 예시

```bash theme={null}
curl "https://maas.gravitex.ai/prod-api/api/logs/getDailySummary?startDate=2026-07-01&endDate=2026-07-27&pageSize=31&pageNum=1" \
  -H "Authorization: Bearer <your_token>"
```

### 응답 예시

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 2,
    "rows": [
      {
        "billMonth": "202607",
        "billDay": "2026-07-27",
        "billingDateTimezone": "utc+8",
        "account": "your_account",
        "currency": "USD",
        "subtotalBeforeTax": "0.26569400",
        "subtotalAfterDiscount": "0.26569400",
        "totalAmountAfterTax": "0.26569400"
      }
    ]
  }
}
```

***

## 비즈니스 규칙과 약정

1. **금액 정밀도**: 모든 금액 필드는 `string`으로 전송하며 소수점 8자리를 유지하여 JSON number 정밀도 손실을 방지합니다.
2. **금액 일관성**: 동일 청구일·동일 계정에서, 일 요약의 각 금액 필드는 해당일 소비 상세의 대응 금액 필드 합과 같습니다 (페이지를 넘어 합산).
3. **제로 소비일**: 조회 구간 내 소비가 없는 날짜는 기록을 반환하지 않습니다.
4. **데이터 지연**: 청구서 데이터는 T+1이며, 최신 하루 데이터는 다음 날에 조회 가능합니다.
5. **계정 범위와 기업 관리**: 기본적으로 자격 증명은 **자신의 계정** 청구서만 조회할 수 있습니다. 해당 계정이 「**기업 관리**」를 개통하고 주 계정인 경우, 하위 **전체 계정**의 청구서를 볼 수 있습니다 — 이때 `userId`/`userName`를 미전달하면 전체 하위 계정을 반환하고, 전달하면 지정 하위 계정으로 필터링합니다 (하위 계정 자신의 자격 증명은 본인만 조회 가능). **기업 관리 개통은 플랫폼 관리자에게 문의하세요.**
6. **페이지 범위 초과**: `pageNum`이 총 페이지 수를 초과하면 빈 `rows`를 반환하며, `total`은 실제 총수를 유지합니다.