> ## 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 ごとに現在のアカウントのリクエスト回数と実際の控除額を集計します。月次レポート、トレンドグラフ、コスト分析の作成に適しています。1 件ずつエラーを確認する必要がある場合は[呼び出し記録一覧](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` にはその暦日が含まれ、翌日の午前 0 時を境界とします。

## リクエスト例

北京時間で今月の日別/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 の 1 週間の使用量を照会します：

```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` ごとに分けることを優先してください。単位の混在を避けるだけでなく、クエリコストも削減できます。
* 呼び出しがない日付は自動的にゼロ埋めされないため、グラフ作成前にクライアント側で日付軸を補完してください。

## 次のステップ

* [呼び出し記録を確認](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.