APIの概要
Log Query API は、アカウント内で実行されたすべての API 呼び出しの詳細記録を返します。 これには、使用されたモデル、実際に請求された金額、レイテンシ、呼び出しがストリーミングだったかどうか、 および呼び出しが失敗したときのエラーコードが含まれます。 これは 残高照会 API を補完するものです。残高照会では残っているクレジット量がわかり、 ログ照会ではそれがどこに使われたかがわかります。 代表的なユースケースは3つあります:自動照合
期間ごと、またはモデルごとに実際の支出を集計し、自社の課金と照合する
セルフサービスのトラブルシューティング
失敗したリクエストのエラーコードを確認し、パラメータの問題か上流側の問題かを見分ける
サポートチケット
正確な呼び出しを特定できるよう、
request_id をサポートに提供するログはコンソールの Logs ページでも確認できます。この API は同じデータへのプログラム用エントリーポイントであり、自動照合、定期エクスポート、または独自の監視への取り込みを目的としています。手動で確認する場合はコンソールを使用してください — 呼び出し記録の確認方法をご覧ください。
System Token の取得方法
Log Query API は System Token で認証します。これは API キーとは同じものではありません(このページ末尾の重要な注意事項を参照してください)。1
コンソールにアクセス
api.apiyi.com/account/profile にアクセスしてプロフィールページを開きます2
System Token を確認
ページ下部の「アカウントオプション - System Token」セクションを見つけてください
3
AccessToken を生成
アカウントのパスワードを入力すると、その後の API クエリに使用できる AccessToken を受け取れます
API情報
リクエストの詳細
リクエストヘッダー
Query Parameters
Raising
pageSize is the single most effective optimization for this endpoint. At 10 records
per page, an account making 500,000 calls a day needs 50,000 requests; at 5000 per page it needs
100. Two orders of magnitude fewer requests, and the pagination offset drops with it — see
Performance Notes below.A 5000-record page measures roughly 700 KB gzipped and takes about 2.5 seconds. If bandwidth or
memory is tight, 1000 is a comfortable middle ground.パフォーマンスに関する注意
単一リクエストのコストは固定ではありません。それは 3 つの要素に依存します。これらのルールに従えば API は高速ですが、無視するとサーバー側の 60 秒クエリ制限に達し、エラーが返ります。
実践的なルールは 4 つあります。
start_timestampとend_timestampを必ず渡してください。 ウィンドウを省略するのは、この API を呼び出すうえで最も高くつく方法です。pageSizeを引き上げてください。 これは簡単です。1ページあたり 10 件から 1000〜5000 件にすると、リクエスト数を 2 桁減らせて、オフセットもそれに伴って小さくなります。- オフセットを深くするのではなく、ウィンドウを狭めてください。 コストがかかるのは「どのページか」ではなく、「そこにたどり着くまでに何件スキップしたか」であり、それは超線形に増えます。1つの大きなウィンドウを最後までページングするのではなく、24 個の 1 時間ウィンドウに分割し、各ウィンドウを offset 0 から再開するようにしてください。
- 履歴は一度だけバックフィルして保存し、その後は増分だけを同期してください。 古いデータは最新データよりクエリコストがはるかに高いため、同じ履歴を何度も読み直すのは完全な無駄です。
pageSize=1000 でもウィンドウが数十ページかかるなら、その期間の呼び出し量は多いということです — ウィンドウを半分に分け、それぞれを別々に取得してください。これは、さらに深くページングするよりずっと速いです。下の Python 例にある MAX_PAGES 定数は、まさにこれを行っています。60 秒は厳格な上限で、それを超えるとエラーが返ります
サーバーは単一クエリを 60 秒 に制限しています。それを過ぎると遅い応答が返るのではなく、 エラーが返り、そこまでに費やした時間ではデータは一切得られません。 次の 3 つのパターンは、これを引き起こしやすいです。再試行して期待するのではなく、最初から避けてください。
同じパラメータで再試行しても速くはなりません。単にさらに 60 秒かかるだけです。
正しい対応は、時間ウィンドウを狭めるか、
pageSize を引き上げてページングを減らすことです —
どちらにしても、1 回の呼び出しでサーバーが処理するデータ量を減らしてください。
ログタイプ
レスポンス詳細
成功レスポンス例
主要レスポンスフィールド
other フィールドには JSON 文字列 が格納されており、ネストしたオブジェクトではないため、2 回目のパースが必要です
(json.loads() in Python, JSON.parse() in JavaScript). そこには billing_type、
request_path(実際に呼び出されたエンドポイント)、group_ratio、model_ratio、および usage が含まれます。クォータ換算
換算ルール
500,000 クォータ = $1.00 USD
quota ÷ 500,000
例:
quota: 7500→ $0.015 USDquota: 22500→ $0.045 USDquota: 18→ $0.000036 USD
エラー応答
HTTP 401 - 認証に失敗しました
sk- で始まる API キーが
誤ってシステム token として使用されています。
解決策: コンソールでシステム token を再生成し、Authorization には
Bearer プレフィックスなし の生の値を指定してください。
コード例
cURL の例(1ページ、簡易確認)
これを使って token が動作することを確認してください。実際の照合には、下の毎日同期スクリプトを使用してください。
Python の例: 日次の増分同期(cron ジョブとしてすぐ使えます)
これは 推奨される標準的な使い方 です。1日1回実行し、前回の同期以降に新しくなったものだけを取得して、 ローカルの SQLite データベースに書き込みます。再実行しても安全です(レコードはrequest_id で重複排除されます)。また、途中で中断された実行は停止したところから再開されます。
データがローカルにあれば、モデル別、日別、token 別など、必要なあらゆる集計はすべて
ご自身のデータベースに対して実行されるため、そのために再び API に問い合わせる必要はありません。これははるかに高速で、
すでに保持期間を過ぎて消えたデータが欲しくなる問題も回避できます。
Node.js の例(単一の時間枠)
考え方は同じです。1時間ごとに分割し、順番にページングし、ページネーションが深くなりすぎたら時間枠を縮小します。Python の requests ライブラリと Node.js の fetch API はどちらも gzip を自動的に展開するため、
その場合は追加の設定は不要です。明示的な
--compressed フラグが必要なのは curl のみです。Common Scenarios
日次照合(推奨される方法)
上の Python スクリプトを 1 日に 1 回実行するようにスケジュールし、ログをローカルデータベースに保存します。必要な内訳——総支出、モデル別、token別——はすべて、自分のデータベースに対する SQL クエリで取得できます。 これが適切な形である理由は 3 つあります。ローカルのクエリは高速であること、ログの保持期間の影響を受けないこと、そして古い履歴を繰り返し読み直すことで API の速度を落とさずに済むことです。 1 つの model のレコードだけを同期するには、リクエストにmodel_name パラメータを追加します。
失敗した呼び出しの見つけ方
データがローカルにあれば、自分のテーブルを直接クエリします:ゲートウェイによって拒否されたリクエスト(無効なパラメータなど)は、
quota が 0 であり、
課金されません。ログ内の error_code を使うと、「呼び出しが失敗した」のか
「呼び出しは成功したが、結果が気に入らなかった」のかを分けられます。サポートに渡すリクエスト ID の指定
ログ内で問題のある呼び出しを見つけ、サポートにrequest_id を伝えてください。これにより、
エンドツーエンドで正確なリクエストを特定できるため、「ある model への呼び出しが
ある時刻の前後で失敗した」と説明するより、はるかに効率的です。
よくある質問
リクエストが遅い、または完全にタイムアウトする場合は、どうすればよいですか?
リクエストが遅い、または完全にタイムアウトする場合は、どうすればよいですか?
まずは次の3点を確認してください。遅いクエリのほとんどはこのいずれかが原因です:
start_timestampとend_timestampを渡していますか? 時間範囲を省略するのは、この API を呼び出すうえで最もコストが高い方法です — サーバーが履歴全体を検索してしまいます。- ウィンドウが古すぎる、または広すぎませんか? 1か月前のデータを問い合わせるのは、昨日のデータを問い合わせるよりはるかにコストがかかります。期間は1日未満に抑え、大量の場合は1時間単位で分割してください。
pが数千に達していますか? ページネーションのコストは超線形に増加します。対処法は、各ウィンドウで必要なページ数が数十ページ程度で済むように時間範囲を絞る ことであって、1つの大きなウィンドウの中でさらに深くページングすることではありません。
なぜ 10 件しか取得できないのですか?
なぜ 10 件しか取得できないのですか?
10回中9回は、パラメータ名が snake_case で 上限は 5000 で、それを超えると明確なエラーが返ります。大量データの場合は、レスポンスが空配列を返すまでページング(
page_size と書かれていたのが原因です。正しい表記は camelCase の pageSize です。これはこのエンドポイントで唯一の camelCase パラメータで、他はすべて(model_name, token_name, start_timestamp, …)snake_case なので、間違えやすいです。エラーは返されず、サーバーはそのパラメータが存在しないものとして扱い、1ページあたり10件にフォールバックします。p=0, p=1, …)する必要があります — 上の Python と Node.js の例には、その処理がすでに組み込まれています。リクエスト ID で特定の呼び出しを 1 件だけ照会できますか?
リクエスト ID で特定の呼び出しを 1 件だけ照会できますか?
はい — 特定の呼び出しを調査する場合、時間範囲を取得して自分で絞り込むよりもはるかに高速です。
request_id を渡すと、そのレコードだけが返されます:レスポンス内の一部のフィールドが空です — 何か問題がありますか?
レスポンス内の一部のフィールドが空です — 何か問題がありますか?
いいえ。特定のフィールドにはプラットフォーム内部情報が含まれており、通常のアカウントの視点では空、または0になります。これは想定どおりで、照合やトラブルシューティングに必要なフィールドには影響しません —
quota, model_name, error_code, および request_id はすべて完全に埋まっています。console に表示されるグループ名と token_group が異なるのはなぜですか?
console に表示されるグループ名と token_group が異なるのはなぜですか?
API はグループの 識別子 を返し、コンソールはグループの ラベル を表示します。これらは一致しない場合があります — たとえば API は
default を返しますが、コンソールには Default と表示されます。完全な対応表は、公開エンドポイント https://api.apiyi.com/api/pricing の usable_group フィールドで確認できます。これは identifier を label に対応付けます。レポートをコンソールに合わせたい場合は、その対応を自分で適用してください。token のカウントとクォータが一致しないようです — どちらが正しいですか?
token のカウントとクォータが一致しないようです — どちらが正しいですか?
quota を使用してください。これは呼び出しに対して 実際に差し引かれた 量であり、照合に適した唯一のフィールドです。画像生成や動画生成のような呼び出しごとに課金されるモデルでは、レスポンス内の token カウントは課金に関与しないプレースホルダー値である場合があります — それらのモデルは by_count を other.billing_type で返します。どこまで遡ってクエリできますか?
どこまで遡ってクエリできますか?
同期ロジックは、直近 30 日間のみクエリ可能である前提で設計してください。実際にはクエリ可能な範囲は通常もっと長いですが、保持期間については一切保証しません — これはログのクリーンアップポリシーに応じて変わり、その変更は個別には告知されません。計画上の下限を 30 日にしておけば、そのポリシーが変わっても照合処理は壊れません。また、ウィンドウが古いほどクエリコストは高くなります: データがまだ存在していても、到達するのにずっと時間がかかります。そのため、正しいパターンは 1日1回、自分のデータベースに同期する こと、そして過去分析はローカルで実行することです。長期保存したいものは自分でアーカイブしてください — それを取り戻すためにこの API に頼らないでください。
curl で文字化けする、または jq がエラーを出す
curl で文字化けする、または jq がエラーを出す
原因: API は gzip 圧縮コンテンツ(Python の requests ライブラリと Node.js の fetch API は自動的に展開します。
Content-Encoding: gzip)を返しており、curl がそれを展開していないためです。解決策: --compressed フラグを追加してください:ログのクエリはクォータを消費しますか?
ログのクエリはクォータを消費しますか?
いいえ。ログクエリエンドポイントは、いかなるクォータも消費しません。
重要な注意事項
推奨される呼び出しパターン
- 1日に1回同期する — それ以上頻繁に行う必要はありません。各実行では新しいものだけを取得します
pageSizeを 1000〜5000 にする — デフォルトの 10 ではありません。これは他の項目を合わせたものより重要です- 直列で呼び出す。ページ間はおおむね1秒空け、同時実行しないでください
- クライアント側のタイムアウトを 60 秒に設定してください(サーバー側のクエリ制限も 60 秒です)
- 各時間窓は 1 日以下にしてください。大量利用アカウントでは 1 時間単位に分割してください
- タイムアウトした場合は、再試行する前に時間窓を狭めてください — 同じ内容を再試行しても速くはなりません
関連ドキュメント
- 残高照会 API — 残りのアカウントクレジットを確認する
- トークン管理 API — APIキーをプログラムで作成・管理する
- 自分の呼び出し履歴の確認方法 — コンソールで手動確認する
- ログと課金の理解 — 課金項目の読み方