> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 規約と注意点

> 一度読んで AI アシスタントに貼り付ければ、初日によくあるミスを回避できます

## 認証

すべてのリクエストには、`X-API-Key` ヘッダーに API キーを含める必要があります。Python
SDK は `PROFOUND_API_KEY` 環境変数からキーを読み取ります。

<CodeGroup>
  ```python Python theme={null}
  import os
  from profound import Profound

  client = Profound(api_key=os.environ["PROFOUND_API_KEY"])
  categories = client.organizations.categories.list()
  ```

  ```bash curl theme={null}
  curl https://api.tryprofound.com/v1/org/categories \
    -H "X-API-Key: your_api_key_here"
  ```
</CodeGroup>

キーはアプリの **Settings → API Keys** で生成します。パスワードと同様に扱ってください。
キーは、プロンプトの作成やエージェントの実行などの書き込みエンドポイントを含め、
組織のデータへのフルアクセス権を持ちます。

## レート制限

**キーごとに 1 時間あたり 600 リクエスト**です。これを超えると `429 Too Many
Requests` が返されます。可能な場合はレスポンスをキャッシュし、期間比較や
複数アセットのクエリは個別に分散させず、まとめて実行してください。

## `end_date` は排他的 — 1 日加える

`end_date` はその日の**東部時間 (Eastern Time)** における**開始**時点として解釈されるため、
レスポンスには含まれません。`May 10` 全体を含めるには、
`end_date="2026-05-11"` を送信します。

| 表示したい期間 | 送信する値 |
| - | - |
| `May 4 → May 10`(7 日間、両端を含む) | `start_date="2026-05-04", end_date="2026-05-11"` |
| `April 1 → April 30`(1 か月全体) | `start_date="2026-04-01", end_date="2026-05-01"` |

`date_interval` のバケット(`"hour"` / `"day"` / `"week"` / `"month"` /
`"quarter"` / `"year"` / `"relative_week"`)も ET で計算されます。週は
日曜日に始まります。

## 列の位置はリクエストではなく `info.query` から読み取る

レスポンスの各行は、`metrics` と `dimensions` を配列として格納しています。
これらの配列内の値の順序は、`info.query.metrics` と `info.query.dimensions` に
記載された順序であり、リクエストの内容が返されます。
位置をハードコードせず、そこから調べてください。

```python theme={null}
order   = res.info.query["metrics"]
i_score = order.index("visibility_score")
score   = res.data[0].metrics[i_score]
```

レスポンスは常に次のような形式です。

```json theme={null}
{
  "info": {
    "total_rows": 12345,
    "query": {
      "metrics": ["visibility_score", "share_of_voice"],
      "dimensions": ["asset_name"]
    }
  },
  "data": [
    { "metrics": [0.42, 0.17], "dimensions": ["<your-asset>"] }
  ]
}
```

## 期間比較の差分はクライアント側で計算する

API は前の期間からの変化を返しません。同じ呼び出しを 2 回
(現在の期間と、同じ長さの前の期間)実行し、差を求めてください。

## 期間スコアを得るために日次の行を平均しない

`dimensions=["date"]` を指定した呼び出しは 1 日につき 1 行を返します。`date` を
指定しない呼び出しは期間全体で 1 行を返します。これらは**異なる
数値**です。期間スコアはトラフィックで重み付けされていますが、日次の行の
平均はそうではありません。ヘッドラインには `date` なしの呼び出しを、チャートには
`date` ありの呼び出しを使用してください。一方から他方を導出しないでください。

## ページネーション

`pagination.limit` のデフォルトは `10,000`、最大は `50,000` です。
ページネーションが必要かどうかは、`info.total_rows`(すべてのレスポンスで返されます)を
使って判断してください。ほとんどすべてのクエリは 50k の 1 ページに収まります。2 ページ目が
必要になるのは、通常 `dimensions=["url", ...]` を使った重い引用クエリだけです。

```python theme={null}
pagination={"limit": 50000, "offset": 0}
```

さらに必要な場合は、`total_rows` をカバーするまで `offset` を `limit` ずつ
増やしてください。

## フィルター

すべてのレポートエンドポイントは、`{field, operator,
value}` オブジェクトの `filters` 配列を受け付けます。

```json theme={null}
{ "field": "asset_name", "operator": "is", "value": "<your-asset-name>" }
```

| 演算子 | 動作 |
| - | - |
| `is` | 完全一致(スカラー値) |
| `not_is` | 等しくない |
| `in` | 配列内のいずれかの値に一致 |
| `not_in` | 配列内のどの値にも一致しない |
| `contains` | 部分文字列一致(大文字と小文字を区別) |
| `not_contains` | 部分文字列の否定一致(大文字と小文字を区別) |
| `contains_case_insensitive` | 部分文字列一致(大文字と小文字を区別しない) |
| `not_contains_case_insensitive` | 部分文字列の否定一致(大文字と小文字を区別しない) |
| `matches` | 正規表現一致 |

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`)が推奨されます。現時点ではどちらも受け付けられます。

## エラーレスポンス

| ステータス | 意味 | 確認事項 |
| - | - | - |
| `422` | バリデーションエラー | レスポンスボディの `detail` フィールド。 |
| `401` | API キーがない、または無効 | `X-API-Key` ヘッダー、およびキーが失効していないか。 |
| `403` | キーは有効だがアクセス権がない | `category_id` が別の組織に属している可能性があります。 |
| `404` | パスが間違っている | タイプミスまたは API バージョンの誤り。 |
| `429` | レート制限 | 間隔を空けて、600 件/時以下に抑えてください。 |
| `5xx` | サーバーエラー | 指数バックオフで再試行してください。 |

## タイムゾーン

すべてのバケット分けは**東部時間 (Eastern Time)** で行われます。ローカル時計を基準にした
「過去 7 日間」の範囲は、想定とは異なる ET の日付になる場合があります。
スケジュールされたジョブは ET を基準にしてください。

```python theme={null}
from datetime import datetime
from zoneinfo import ZoneInfo

today_et = datetime.now(ZoneInfo("America/New_York")).date()
```