> ## 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 플랫폼 Proxy 호출 기록 가져오기

> Platform API guide - Ace Data Cloud

현재 계정의 Proxy 유형 서비스에서 사용량 기록을 조회합니다. 일반 API 호출에는 [API 호출 기록](https://platform.acedata.cloud/documents/platform-usage-list)을 사용하세요. 서비스 유형이 확실하지 않으면 먼저 [서비스 상세](https://platform.acedata.cloud/documents/platform-service-detail)의 `type`을 확인할 수 있습니다.

## 준비 작업

1. [AceDataCloud 플랫폼](https://platform.acedata.cloud)에 로그인합니다.
2. [Account Token 콘솔](https://platform.acedata.cloud/console/platform-tokens)에서 계정 토큰을 생성하고, 즉시 비밀번호 관리자 또는 Secret Manager에 저장합니다.
3. [개인 프로필 페이지](https://auth.acedata.cloud/user/profile)를 열어 현재 계정 UUID를 복사하고 `USER_ID`로 저장합니다. 계정 토큰 생성 응답의 `user_id`도 사용할 수 있습니다.
4. [서비스 신청 목록](https://platform.acedata.cloud/documents/platform-application-list)에서 Proxy 유형 서비스의 `application_id`를 가져옵니다. Proxy 엔드포인트별로 필터링해야 하는 경우 [서비스의 Proxy 목록](https://platform.acedata.cloud/documents/platform-service-proxies)에서 `proxy_id`를 가져옵니다.

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

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export USER_ID='你的账户 UUID'
export APPLICATION_ID='你的 Proxy Application ID'
```

## 인터페이스 개요

| 항목 | 내용 |
| - | - |
| 메서드 | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/proxies/` |
| 인증 | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| Scope | `usage:read` |
| 페이지네이션 | `count` + `items`, 기본적으로 페이지당 10개 |

Application 소유자가 `application_id`로 조회할 때 서버는 먼저 해당 Application의 사용 가능한 기록을 동기화한 후 목록을 반환하므로, 응답 시간이 일반 API usage 목록보다 길 수 있습니다. 권한을 부여받은 사용자는 기존에 표시 가능한 기록을 읽을 수 있지만, 소유자 측 동기화를 트리거하지는 않습니다.

## 쿼리 매개변수

| 매개변수 | 유형 | 필수 | 기본값 | 설명 |
| - | - | - | - | - |
| `user_id` | UUID | 일반 사용자 필수 | — | 현재 계정 UUID, 다른 계정을 전달하면 `403`이 반환됩니다 |
| `application_id` | UUID | 권장 | — | Proxy Application별 필터링, 반복 매개변수 지원 |
| `proxy_id` | UUID | 아니요 | — | Proxy 엔드포인트별 필터링, 반복 매개변수 지원 |
| `limit` | integer | 아니요 | 10 | 페이지당 항목 수, 최대 100 |
| `offset` | integer | 아니요 | 0 | 페이지네이션 오프셋 |
| `ordering` | string | 아니요 | `-created_at` | 생성 시간 내림차순 |

현재 인터페이스는 모델, HTTP 상태 코드, Credential 또는 시간 범위로 직접 필터링하는 것을 지원하지 않으며, API usage 인터페이스의 `perspective` 매개변수도 지원하지 않습니다. 이러한 지원되지 않는 매개변수를 요청에 추가하고 적용되었다고 가정하지 마세요.

## 요청 예시

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

Python 페이지네이션 예시:

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

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/proxies/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "user_id": os.environ["USER_ID"],
        "application_id": os.environ["APPLICATION_ID"],
        "limit": 100,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["deducted_amount"], usage["remaining_amount"])
```

## 응답 예시

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": null,
      "application_id": "00000000-0000-4000-8000-000000000003",
      "proxy_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": null,
      "used_amount": null,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "metadata": null,
      "created_at": "2026-09-01T08:00:00Z",
      "updated_at": "2026-09-01T08:00:00Z",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "title": "Example Proxy Service"
      },
      "credential": null
    }
  ]
}
```

## 주요 필드

| 필드 | 설명 |
| - | - |
| `user_id` | 이번 청구를 부담하는 계정 |
| `actor_user_id` | 실제 호출자, 이전 기록에서는 비어 있을 수 있음 |
| `application_id` | 해당 기록을 생성한 Proxy Application |
| `proxy_id` | 해당 Proxy 엔드포인트 |
| `credential_id` | 연결된 자격 증명 ID, 이전 기록에서는 비어 있을 수 있음 |
| `used_amount` | 원본 기록의 사용량, 비어 있을 수 있음 |
| `deducted_amount` | 최종 실제 차감된 한도 |
| `remaining_amount` | 청구 후 Application의 남은 한도 |
| `metadata` | 공개 메타데이터, 비어 있을 수 있음 |
| `service` / `credential` | 표시를 위한 연결 객체 요약, 연결 객체가 존재하지 않으면 비어 있을 수 있음 |

한도 단위는 해당 Application의 `service.unit`에 따라 결정됩니다.

## 오류 처리

| HTTP | 의미 | 처리 방법 |
| - | - | - |
| 401 | 계정 토큰이 없거나 유효하지 않음 | Account Token을 확인하고, 비즈니스 Credential을 잘못 사용하지 마세요 |
| 403 | 요청의 기록을 볼 권한이 없음 | 현재 계정에 속한 Application을 사용하고, 권한 없는 `user_id`를 제거하세요 |
| 5xx | 동기화 또는 쿼리가 일시적으로 실패 | 필터 조건을 유지하고 백오프 재시도하세요. 지속적으로 실패하면 Application ID와 시간을 지원 담당자에게 제공하세요 |

## 다음 단계

* [API 호출 기록 보기](https://platform.acedata.cloud/documents/platform-usage-list): 일반 API 유형 서비스의 상세 내역을 조회합니다.
* [서비스의 Proxy 목록 가져오기](https://platform.acedata.cloud/documents/platform-service-proxies): `proxy_id`를 가져옵니다.
* [서비스 신청 상세 보기](https://platform.acedata.cloud/documents/platform-application-detail): 남은 한도와 단위를 확인합니다.


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