> ## 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`、デフォルトで 1 ページあたり 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 | 1 ページあたりの件数、最大 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` | クエリがサーバー側の安全な制限時間を超過した | 時間範囲を縮小するかフィルター条件を追加してから再試行する |

同じ一連のクエリパラメータについて、進行中のリクエストは最大 1 つまで保持されます。広範囲のクエリでは、1 日以下のウィンドウを優先して使用し、固定間隔で同一リクエストを重ねないでください。

## 次のステップ

* [呼び出し量を集計する](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.