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

# AceDataCloud 플랫폼 API 호출량 집계 통계 조회

> Platform API guide - Ace Data Cloud

날짜와 API별로 현재 계정의 요청 횟수 및 실제 차감된 할당량을 집계하며, 월간 보고서, 추세 그래프 및 비용 분석에 적합합니다. 항목별 오류를 확인해야 할 때는 [호출 기록 목록](https://platform.acedata.cloud/documents/platform-usage-list)을 사용하고, 전체 오프라인 상세 내역이 필요할 때는 [호출량 내보내기](https://platform.acedata.cloud/documents/platform-usage-export)를 사용하세요.

## 준비 작업

1. [AceDataCloud 플랫폼](https://platform.acedata.cloud)에 로그인합니다.
2. [Account Token 콘솔](https://platform.acedata.cloud/console/platform-tokens)에서 계정 토큰을 생성하고 즉시 저장합니다.
3. 범위를 좁혀야 하는 경우 [서비스 신청 목록](https://platform.acedata.cloud/documents/platform-application-list), [API 자격 증명 목록](https://platform.acedata.cloud/documents/platform-credential-list) 또는 [API 목록](https://platform.acedata.cloud/documents/platform-api-list)에서 해당 ID를 가져옵니다.

전체 토큰 설명은 [계정 토큰 관리](https://platform.acedata.cloud/documents/platform-token)를 참조하세요. 이 인터페이스는 Account Token을 사용하며, 비즈니스 Credential은 사용하지 않습니다.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
```

## 인터페이스 개요

| 항목 | 내용 |
| - | - |
| 메서드 | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| 인증 | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read`（`platform:read` / `platform`에 포함되어 확장 가능） |
| 권한 범위 | 일반 사용자는 자신의 유료 사용량으로 고정; 관리자는 `user_id`를 전달할 수 있음 |

## 쿼리 파라미터

| 파라미터 | 유형 | 필수 | 기본값 | 설명 |
| - | - | - | - | - |
| `created_at_from` | date / datetime | 아니요 | 선택한 시간대의 이번 달 첫날 | 시작 시간, 권장 파라미터 이름 |
| `created_at_to` | date / datetime | 아니요 | 현재 시간 | 종료 시간, 권장 파라미터 이름 |
| `timezone` | string | 아니요 | `UTC` | IANA 시간대, 예: `Asia/Shanghai`; 유효하지 않은 값은 UTC로 대체 |
| `service_id` | UUID | 아니요 | — | 서비스별 필터링; 반복 파라미터 지원 |
| `application_id` | UUID | 아니요 | — | Application별 필터링; 반복 파라미터 지원 |
| `api_id` | UUID | 아니요 | — | API별 필터링; 반복 파라미터 지원 |
| `credential_id` | UUID | 아니요 | — | API 자격 증명별 필터링; 반복 파라미터 지원 |
| `include_models` | boolean | 아니요 | `false` | 모델 차원 집계를 추가로 계산할지 여부; 쿼리 비용 증가 |
| `user_id` | UUID | 아니요 | 일반 사용자는 자신으로 고정; 관리자는 전달하지 않으면 모든 계정 | 관리자만 임의의 계정을 지정할 수 있음 |

`start_time` / `end_time`은 이전 클라이언트 호환 별칭으로 계속 사용할 수 있으며, 새 연동에서는 `created_at_from` / `created_at_to`를 통일하여 사용합니다. 날짜 형식의 `created_at_to`는 해당 자연일을 포함하며, 즉 다음 날 자정을 경계로 합니다.

## 요청 예시

베이징 시간 기준 이번 달의 일별/API 집계를 조회하고, 모델 차원도 포함합니다:

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  --data-urlencode 'include_models=true' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

지정한 Application의 일주일 사용량을 조회합니다:

```shell theme={null}
export APPLICATION_ID='你的 Application ID'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01' \
  --data-urlencode 'created_at_to=2026-09-07' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Python 예시:

```python theme={null}
import os
import requests

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/apis/aggregate/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "created_at_from": "2026-09-01",
        "created_at_to": "2026-09-07",
        "timezone": "Asia/Shanghai",
        "include_models": "true",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print("requests:", data["requests"], "deducted:", data["total"])
for row in data["items"]:
    print(row["date"], row["api_id"], row["amount"])
```

## 응답 예시

```json theme={null}
{
  "items": [
    {
      "date": "2026-09-01",
      "api_id": "00000000-0000-4000-8000-000000000001",
      "amount": 12.5
    }
  ],
  "total": 12.5,
  "apis": {
    "00000000-0000-4000-8000-000000000001": {
      "title": "Example API"
    }
  },
  "requests": 42,
  "models": [
    {
      "model": "example-model",
      "amount": 12.5,
      "requests": 42
    }
  ]
}
```

## 응답 필드

| 필드 | 설명 |
| - | - |
| `items` | 선택한 시간대의 날짜와 `api_id`별 그룹화; 각 행에는 `date`, `api_id`, `amount`가 포함됨 |
| `total` | 쿼리 범위 내 `deducted_amount`의 합계 |
| `apis` | API ID에서 제목 요약으로의 매핑으로, `items` 표시를 편리하게 함 |
| `requests` | 쿼리 범위 내 총 요청 수 |
| `models` | `include_models=true`일 때만 계산됨; 각 항목에는 `model`, `amount`, `requests`가 포함됨 |

할당량 단위는 관련 Application의 `service.unit`에 따라 달라집니다. 쿼리에 서로 다른 단위의 서비스가 포함된 경우, 직접 비교하거나 합산하지 않도록 먼저 `service_id` 또는 `application_id`별로 나누어 집계하세요.

종료 시간이 시작 시간보다 작거나 같으면, 인터페이스는 완전한 빈 구조를 반환합니다: `items=[]`, `total=0`, `apis={}`, `requests=0`, `models=[]`.

## 오류 및 성능 권장 사항

| HTTP | `error` | 처리 방법 |
| - | - | - |
| 400 | `usage_history_expired` | 시간 범위를 응답의 `available_from` 이후로 조정 |
| 401 | `not_authenticated` | Account Token을 확인하고, 비즈니스 Credential을 잘못 사용하지 마세요 |
| 403 | `permission_denied` | 일반 사용자는 다른 계정을 조회할 수 없음 |

* 기본적으로 `include_models`를 활성화하지 마세요. 보고서에 실제로 모델 분류가 필요한 경우에만 활성화하세요.
* 넓은 범위의 쿼리는 우선 `service_id` 또는 `application_id`별로 나누어, 단위 혼합을 방지하고 쿼리 비용도 줄이세요.
* 호출이 없는 날짜는 자동으로 0으로 채워지지 않으므로, 그래프를 그리기 전에 클라이언트에서 날짜 축을 보완하세요.

## 다음 단계

* [호출 기록 보기](https://platform.acedata.cloud/documents/platform-usage-list)：집계 결과를 구성하는 상세 내역을 확인합니다.
* [호출량 내보내기](https://platform.acedata.cloud/documents/platform-usage-export)：전체 CSV 상세 내역을 다운로드합니다.
* [서비스 신청 상세 보기](https://platform.acedata.cloud/documents/platform-application-detail)：잔액과 단위를 확인합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.