> ## 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

현재 계정의 최근 60일 비즈니스 API 호출 상세 내역을 조회하며, 과금 대조, 실패 요청 위치 파악 및 서비스, Application, API 또는 자격 증명별 문제 조사에 적합합니다.

> 이 페이지에서 조회하는 것은 계정 자체의 호출 내역입니다. 특정 API의 전체 플랫폼 공개 호출 통계만 확인하려면 [API 호출 통계](https://platform.acedata.cloud/documents/platform-api-usage)를 사용하세요.

## 준비 작업

### 1. 계정 토큰 생성

이 인터페이스는 플랫폼 관리 API에 속하며, **Account Token(계정 토큰)** 을 사용해야 합니다.

1. [AceDataCloud 플랫폼](https://platform.acedata.cloud)에 로그인합니다.
2. [Account Token 콘솔](https://platform.acedata.cloud/console/platform-tokens)을 엽니다.
3. 「생성」을 클릭하고, 즉시 토큰을 비밀번호 관리자 또는 Secret Manager에 저장합니다.

전체 설명은 [AceDataCloud 플랫폼 계정 토큰 관리](https://platform.acedata.cloud/documents/platform-token)를 참조하세요. 계정 토큰은 `platform.acedata.cloud/api/v1/**`에 사용됩니다. `api.acedata.cloud/**` 비즈니스 인터페이스 호출에는 API 자격 증명(Credential)을 사용하며, 둘은 혼용할 수 없습니다.

```shell theme={null}
export PLATFORM_TOKEN='당신의 계정 토큰'
```

토큰을 프런트엔드 코드, 로그 또는 공개 저장소에 작성하지 마세요. 유출된 경우 즉시 콘솔에서 삭제하고 다시 생성하세요.

### 2. 필터 ID 준비(선택 사항)

필터 조건을 전달하지 않으면 현재 계정이 조회할 권한이 있는 기록을 확인할 수 있습니다. 범위를 좁혀야 하는 경우:

* `application_id`: [서비스 신청 목록](https://platform.acedata.cloud/documents/platform-application-list)에서 가져옵니다.
* `credential_id`: [API 자격 증명 목록](https://platform.acedata.cloud/documents/platform-credential-list)에서 가져옵니다.
* `api_id`: [API 목록](https://platform.acedata.cloud/documents/platform-api-list)에서 가져옵니다.
* `service_id`: [서비스 목록](https://platform.acedata.cloud/documents/platform-service-list)에서 가져옵니다.

일반 사용자는 `user_id`를 전달할 필요가 없습니다. 명시적으로 전달하는 경우 현재 계정과 일치해야 하며, 그렇지 않으면 `403`이 반환됩니다. 관리자는 이 매개변수를 사용하여 계정 간 필터링을 할 수 있습니다.

## 인터페이스 개요

| 항목 | 내용 |
| - | - |
| 메서드 | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/` |
| 인증 | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read`(`platform:read` / `platform`는 확장하여 포함 가능) |
| 페이지네이션 | `count` + `items`, 기본 페이지당 10개 |

## 조회 범위

| `perspective` | 의미 |
| - | - |
| `both` | 기본값; 현재 계정이 비용을 지불했거나 실제로 호출한 기록을 반환 |
| `billing` | 현재 계정이 비용을 지불한 기록만 반환 |
| `actor` | 현재 계정이 실제로 호출한 기록만 반환 |

## 쿼리 매개변수

| 매개변수 | 유형 | 필수 | 기본값 | 설명 |
| - | - | - | - | - |
| `perspective` | string | 아니요 | `both` | `billing`, `actor` 또는 `both` |
| `user_id` | UUID | 아니요 | — | 관리자만 사용자별 필터링; 반복 매개변수 지원 |
| `service_id` | UUID | 아니요 | — | 서비스별 필터링; 반복 매개변수 지원 |
| `application_id` | UUID | 아니요 | — | Application별 필터링; 반복 매개변수 지원 |
| `api_id` | UUID | 아니요 | — | API별 필터링; 반복 매개변수 지원 |
| `credential_id` | UUID | 아니요 | — | API 자격 증명별 필터링; 반복 매개변수 지원 |
| `status_code` | integer | 아니요 | — | HTTP 상태 코드별 필터링; 반복 또는 쉼표로 구분된 값 지원 |
| `created_at_from` | datetime | 아니요 | — | 생성 시간 하한, ISO 8601 |
| `created_at_to` | datetime | 아니요 | — | 생성 시간 상한, ISO 8601 |
| `limit` | integer | 아니요 | 10 | 페이지당 항목 수, 최대 100 |
| `offset` | integer | 아니요 | 0 | 페이지네이션 오프셋 |
| `ordering` | string | 아니요 | `-created_at` | 생성 시간 내림차순 |

요청 시간이 최근 60일보다 이전인 경우, 인터페이스는 `400` 필드 검증 오류를 반환하며 전체 호출 상세 내역은 60일만 보관된다고 안내합니다.

## 요청 예시

최근 100개 기록 조회:

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode 'perspective=both' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

시간, Application 및 실패 상태별 필터링:

```shell theme={null}
export APPLICATION_ID='당신의 Application ID'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01T00:00:00Z' \
  --data-urlencode 'created_at_to=2026-09-02T00:00:00Z' \
  --data-urlencode 'status_code=500' \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Python 페이지네이션 예시:

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

url = "https://platform.acedata.cloud/api/v1/usage/apis/"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}
params = {"perspective": "both", "limit": 100, "offset": 0}

response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["status_code"], usage["deducted_amount"], usage["trace_id"])

if params["offset"] + len(data["items"]) < data["count"]:
    params["offset"] += len(data["items"])
```

## 응답 예시

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": "00000000-0000-4000-8000-000000000002",
      "application_id": "00000000-0000-4000-8000-000000000003",
      "api_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": "00000000-0000-4000-8000-000000000005",
      "trace_id": "example-trace-id",
      "status_code": 200,
      "used_amount": 1.25,
      "original_amount": 1.25,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "started_at": "2026-09-01T08:00:00Z",
      "finished_at": "2026-09-01T08:00:01Z",
      "elapsed": 1.0,
      "created_at": "2026-09-01T08:00:01Z",
      "updated_at": "2026-09-01T08:00:01Z",
      "metadata": {"model": "example-model"},
      "api": {"title": "Example API"},
      "service": {"id": "00000000-0000-4000-8000-000000000006", "title": "Example Service"},
      "credential": {"id": "00000000-0000-4000-8000-000000000005", "name": "Production"}
    }
  ]
}
```

## 주요 필드

| 필드 | 설명 |
| - | - |
| `user_id` | 이번 차감 비용을 부담하는 계정 |
| `actor_user_id` | 실제로 호출을 시작한 계정; 다른 사람에게 자격 증명 사용을 허용한 경우 `user_id`와 다를 수 있음 |
| `used_amount` | 이번 호출에 대해 원래 규칙으로 계산된 사용량 |
| `original_amount` | 애플리케이션 할인 전의 원래 사용량 |
| `deducted_amount` | 최종적으로 실제 차감된 할당량 |
| `remaining_amount` | 이번 차감 완료 후 Application의 남은 할당량 |
| `elapsed` | 서버 측에서 기록한 호출 소요 시간이며, 단위는 초 |
| `trace_id` | 단일 요청을 조사할 때 사용하는 추적 식별자 |
| `metadata` | 공개 메타데이터; 목록은 전체 요청 또는 응답 내용을 반환하지 않음 |
| `api` / `service` / `credential` | 표시에 편리한 연결 객체 요약; 연결 객체가 더 이상 존재하지 않을 경우 비어 있을 수 있음 |

할당량 단위는 해당 Application의 `service.unit`에 의해 결정되며, 기본적으로 미국 달러로 간주해서는 안 됩니다.

## 오류 및 재시도

| HTTP | `error` | 의미 | 처리 방식 |
| - | - | - | - |
| 400 | 필드 유효성 검사 오류 | 조회 범위가 60일 보존 기간보다 이전임 | 시작 시간을 최근 60일 이내로 조정 |
| 401 | `not_authenticated` | 계정 토큰이 없거나 유효하지 않음 | Account Token을 확인하고, 비즈니스 Credential을 잘못 사용하지 마세요 |
| 403 | `permission_denied` | 요청에 볼 권한이 없는 기록이 포함됨 | 권한이 없는 사용자 필터 조건을 제거 |
| 429 | `usage_query_in_progress` | 완전히 동일한 조회가 아직 실행 중임 | `Retry-After`를 기다린 후 백오프 재시도 |
| 503 | `usage_query_timeout` | 조회가 서버 측 안전 시간 제한을 초과함 | 시간 범위를 줄이거나 필터 조건을 추가한 후 재시도 |

동일한 쿼리 매개변수 그룹은 진행 중인 요청을 최대 하나만 유지합니다. 넓은 범위의 조회는 하루 또는 그보다 작은 창을 우선 사용하고, 고정 간격으로 동일한 요청을 중첩하지 마세요.

## 다음 단계

* [호출량 집계](https://platform.acedata.cloud/documents/platform-usage-aggregate)：날짜 및 API별로 집계된 사용량을 확인합니다.
* [호출량 내보내기](https://platform.acedata.cloud/documents/platform-usage-export)：대량의 상세 내역을 CSV로 직접 다운로드합니다.
* [Proxy 호출 기록 보기](https://platform.acedata.cloud/documents/platform-proxy-usage)：Proxy 유형 서비스의 기록을 조회합니다.
* [서비스 신청 세부 정보 보기](https://platform.acedata.cloud/documents/platform-application-detail)：잔액 및 할당량 단위를 확인합니다.
* [API 자격 증명 교체](https://platform.acedata.cloud/documents/platform-credential-rotate)：자격 증명 유출이 의심되는 경우 즉시 교체합니다.


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