認証
すべてのリクエストには、X-API-Key ヘッダーに API キーを含める必要があります。Python
SDK は PROFOUND_API_KEY 環境変数からキーを読み取ります。
レート制限
キーごとに 1 時間あたり 600 リクエストです。これを超えると429 Too Many Requests が返されます。可能な場合はレスポンスをキャッシュし、期間比較や
複数アセットのクエリは個別に分散させず、まとめて実行してください。
end_date は排他的 — 1 日加える
end_date はその日の東部時間 (Eastern Time) における開始時点として解釈されるため、
レスポンスには含まれません。May 10 全体を含めるには、
end_date="2026-05-11" を送信します。
date_interval のバケット("hour" / "day" / "week" / "month" /
"quarter" / "year" / "relative_week")も ET で計算されます。週は
日曜日に始まります。
列の位置はリクエストではなく info.query から読み取る
レスポンスの各行は、metrics と dimensions を配列として格納しています。
これらの配列内の値の順序は、info.query.metrics と info.query.dimensions に
記載された順序であり、リクエストの内容が返されます。
位置をハードコードせず、そこから調べてください。
期間比較の差分はクライアント側で計算する
API は前の期間からの変化を返しません。同じ呼び出しを 2 回 (現在の期間と、同じ長さの前の期間)実行し、差を求めてください。期間スコアを得るために日次の行を平均しない
dimensions=["date"] を指定した呼び出しは 1 日につき 1 行を返します。date を
指定しない呼び出しは期間全体で 1 行を返します。これらは異なる
数値です。期間スコアはトラフィックで重み付けされていますが、日次の行の
平均はそうではありません。ヘッドラインには date なしの呼び出しを、チャートには
date ありの呼び出しを使用してください。一方から他方を導出しないでください。
ページネーション
pagination.limit のデフォルトは 10,000、最大は 50,000 です。
ページネーションが必要かどうかは、info.total_rows(すべてのレスポンスで返されます)を
使って判断してください。ほとんどすべてのクエリは 50k の 1 ページに収まります。2 ページ目が
必要になるのは、通常 dimensions=["url", ...] を使った重い引用クエリだけです。
total_rows をカバーするまで offset を limit ずつ
増やしてください。
フィルター
すべてのレポートエンドポイントは、{field, operator, value} オブジェクトの filters 配列を受け付けます。
UUID フィルター(
model_id、region_id、topic_id、tag_id、persona_id)は
is、not_is、in、not_in のみを受け付けます。部分文字列と正規表現の
演算子は、asset_name、root_domain、url などの名前ベースのフィールドに
適用されます。
prompt_type("visibility" などの値)は、アプリの
Prompt Type フィルターに対応します。デフォルトの UI スコープに合わせるには、Citations クエリで
prompt_type=visibility を送信してください。prompt_type は非推奨となり、
analysis_type(値は visibility、sentiment、sentiment_v2、
accuracy)が推奨されます。現時点ではどちらも受け付けられます。