請求 Public API

自社の請求ツールからアカウント残高、モデル使用量、モデル費用を照会する

請求 Public API は、スクリプト、ダッシュボード、財務システムから Atlas Cloud の請求データを読み取るための API です。

Base URL: https://api.atlascloud.ai/public/v1

エンドポイント

Endpoint	説明
`GET /balance`	現在のアカウント残高とクレジット概要
`GET /model-usage`	UTC 日単位のモデル使用量
`GET /model-costs`	UTC 日単位のモデル費用

詳しいリクエストとレスポンスのスキーマは API リファレンスを参照してください：

認証

Atlas Cloud API Key を Authorization header に指定します：

Authorization: Bearer apikey-...

API Key は API Keys で作成できます。シークレットキーは apikey- で始まります。

一部のレスポンスとフィルターでは ak_... 形式の API Key public ID を使います。これは請求レポートに表示できますが、認証情報ではありません。

権限

/model-usage と /model-costs はデフォルトで scope=self を使い、認証ユーザーに帰属する使用量を返します。これにはそのユーザーが所有する API Key も含まれます。

scope=account を使うとアカウント全体の使用量と費用を取得できます。これには account-level model billing read permission が必要です。/balance は常に account scope で、account balance read permission が必要です。

個人アカウントの owner は自分の請求データを読み取れます。チームアカウントでは Account Admin または Finance ロールを使ってください。

残高の取得

curl "https://api.atlascloud.ai/public/v1/balance" \
  -H "Authorization: Bearer apikey-..."

金額は小数 6 桁の文字列と currency で返されます：

{
  "value": "125.500000",
  "currency": "usd"
}

使用量と費用のクエリパラメーター

start_date と end_date は必須の UTC 日付で、形式は YYYY-MM-DD です。end_date は排他的で、最大 180 日まで指定できます。

/model-usage と /model-costs の共通クエリパラメーター。group_by[] を省略すると日次合計を返します：

パラメーター	説明
`start_date`	`YYYY-MM-DD` 形式の UTC 開始日（含む）
`end_date`	`YYYY-MM-DD` 形式の UTC 終了日（含まない）。範囲は最大 180 日です
`scope`	`self` または `account`。デフォルトは `self`
`group_by[]`	任意のグループ化。対応セット: `model_type`、`model`、`api_key`、または `model` と `api_key`。モデル別内訳には `group_by[]=model` を指定します
`model_types[]`	`text`、`image`、`video` を繰り返し指定
`model_ids[]`	モデル ID で絞り込み。最大 100 個
`api_key_ids[]`	`ak_...` の API Key public ID で絞り込み。最大 100 個
`limit`	1 ページの行数。1 から 1000、デフォルト 100
`page`	`next_page` から受け取った不透明な cursor

配列パラメーターは繰り返し形式で送信してください。カンマ区切り値は拒否されます。

使用量の取得

デフォルトのレスポンスは日次使用量合計を返します。

curl "https://api.atlascloud.ai/public/v1/model-usage?start_date=2026-05-01&end_date=2026-05-08" \
  -H "Authorization: Bearer apikey-..."

費用の取得

/model-costs は /model-usage と同じ日付範囲、scope、フィルター、グループ化、ページネーションパラメーターを受け付けます。group_by[] を省略すると日次費用合計を返します。

curl "https://api.atlascloud.ai/public/v1/model-costs?start_date=2026-05-01&end_date=2026-05-08&scope=account&group_by[]=model&group_by[]=api_key" \
  -H "Authorization: Bearer apikey-..."

ページネーション

has_more が true の場合、next_page をそのまま page クエリパラメーターとして渡します。cursor は不透明値として扱い、他のクエリパラメーターは変更しないでください。

エラーとレート制限

エラーは安定した envelope で返されます：

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date",
    "message": "start_date must be YYYY-MM-DD",
    "param": "start_date"
  },
  "request_id": "req_..."
}

レート制限時は 429 rate_limit_error を返し、Retry-After header を含む場合があります。

目次