> ## 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.

# フィルタリングと概念

> v2 レポートエンドポイントの仕組み: 共通のリクエスト形式、フィルタツリー、グループ化、スコープ、ページネーション、ストリーミング

v2 レポートエンドポイントは **共通のリクエスト形式とレスポンス形式** を使用します:
[可視性](/ja-jp/rest-api/reports/query-visibility-v2)、
[引用](/ja-jp/rest-api/reports/query-citations-v2)、
[センチメント](/ja-jp/rest-api/reports/query-sentiment-v2)、
[クエリファンアウト](/ja-jp/rest-api/reports/query-fanouts-v2)、
[回答](/ja-jp/rest-api/reports/query-answers-v2)、および
[FactCheck](/ja-jp/rest-api/reports/query-factcheck-v2) (正確性スコア +
[主張](/ja-jp/rest-api/reports/query-factcheck-claims-v2))。一度覚えれば、すべての
レポートが同じように動作します。YouTube ソーシャルレポートも v2 レポートであり、
チャンネルや動画に固有のグループ化と帰属のフィールドを持ちます。エンドポイント固有の
リクエストおよびレスポンスのフィールドについては、[YouTube チャンネル](/ja-jp/rest-api/reports/query-youtube-channels-v2) と
[YouTube 動画](/ja-jp/rest-api/reports/query-youtube-videos-v2) を参照してください。

<Note>
  FactCheck は同じ `{ info, data }` エンベロープを使用しますが、**カテゴリ単位** (
  `scope`/`assets`/`metrics` パラメータなし) で、**より限定的な `filter`** を受け付けます。
  単一フィールドのリーフをトップレベルの `and` で結合したもので、否定できるのは `topic` のみです。詳細は
  各ページを参照してください。
</Note>

<Note>
  すべての v2 エンドポイントは、フィルタが値を受け取る箇所で **名前または UUID** を受け付けます。
  UUID は `GET /v1/org/models`、`/v1/org/regions`、`/v1/org/personas`、
  `/v1/org/assets`、`/v1/org/categories`、およびカテゴリごとの
  `…/topics`、`…/tags`、`…/prompts` エンドポイントから取得できます。
</Note>

## 共通のリクエストフィールド

| フィールド | 型 | 備考 |
| - | - | - |
| `category_id` | UUID (必須) | クエリ対象のカテゴリ。 |
| `start_date` / `end_date` | date (必須) | `YYYY-MM-DD`、米国東部時間で、開始日と終了日の **両方を含みます**。 |
| `scope` | `owned` · `all` | 自社所有のアセット/ドメインに限定するか、すべてをランク付けするか。デフォルトはレポートによって異なります。 |
| `group_by` | string\[] | ディメンションごとに結果を行に分割します ([グループ化](#grouping) を参照)。 |
| `metrics` | string\[] | 計算する指標。**各行の名前付きフィールド** として返されます。 |
| `interval` | `day` · `week` · `month` | `date` でグループ化する際のバケットサイズ。デフォルトは `day`。 |
| `filter` | tree | `and`/`or`/`not`/リーフのツリー ([フィルタ](#filters) を参照)。 |
| `sort` | `{ field, dir }` | 行の並び順 (サポートされている場合)。 |
| `limit` | `1`–`50` | 1 ページあたりの行数。デフォルトは `10`。 |
| `cursor` | string | `info.next_cursor` から取得したページトークン。 |

<Warning>
  v1 レポート (`end_date` を含まない) とは異なり、**v2 の `end_date` は
  終了日を含みます**。6 月 9 日から 15 日までを取得するには、`start_date: "2026-06-09"`、
  `end_date: "2026-06-15"` を送信します。
</Warning>

## グループ化

`group_by` は、1 つの集計行を値ごとの 1 行に変換します。グループ化した各フィールドは
行にエコーされます。

```json theme={null}
// group_by: ["model"]  →  each row carries the model it's for
{ "asset": { "name": "Profound", "owned": true }, "model": { "id": "…", "name": "ChatGPT" }, "visibility_score": 0.52 }
```

* 時系列を取得するには、`date` (および `interval`) でグループ化します。
* **日付以外** のディメンションでグループ化した場合、行には `rank` が含まれます。
* 利用可能なディメンションはレポートによって異なります。各エンドポイントのリファレンスを参照してください。

## 指標

必要な指標をリクエストすると、各行の **名前付きフィールド** として返されます
(位置ベースの配列や `info.query` の参照は不要です)。

```json theme={null}
{ "rank": 1, "visibility_score": 0.48, "share_of_voice": 0.077, "average_position": 2.5 }
```

## スコープとアセットの選択

* **`scope`:** `owned` は自社所有のアセット/ドメインに限定し、`all` はすべてを対象にランク付けします。
* **可視性のみ:** 別の **`assets`** パラメータでアセットを選択します。名前
  (`is`)、リスト (`in`。`scope` より優先されます)、または `{ op, value }` を指定します。
  選択した場合は一致するものがすべて返され、`limit` は無視されます。
* **センチメント** では **`asset`** が必須です (センチメントはブランド単位のため)。

## フィルタ

`filter` は **最大深さ 3** の再帰的なツリーで、YouTube ソーシャルレポートを含む
すべてのレポートで使用できます。

```json theme={null}
{
  "and": [
    { "or":  [ { "field": "model", "op": "is", "value": "ChatGPT" },
               { "field": "model", "op": "is", "value": "Perplexity" } ] },
    { "not": { "field": "region", "op": "is", "value": "United States" } }
  ]
}
```

ノードの種類: `{ "and": [ … ] }`、`{ "or": [ … ] }`、`{ "not": <node> }`、および
リーフ `{ "field", "op", "value" }`。

### 演算子

| 演算子 | 意味 |
| - | - |
| `is` / `not_is` | 完全一致 / その否定 |
| `in` / `not_in` | リスト (空でないもの) 内のいずれかの値に一致 / その否定 |
| `contains` / `not_contains` | 部分文字列 (大文字と小文字を区別) |
| `contains_case_insensitive` / `not_contains_case_insensitive` | 部分文字列 (大文字と小文字を区別しない) |
| `matches` | 正規表現 (パターンは 3 文字以上) |
| `exists` | 何らかの値を持つ。`tag` / `persona` のみ (「なし」にするには `not` で囲みます) |

`value` は単一の値、または `in` / `not_in` の場合はリストです。名前 **または** UUID を指定できます。
`contains` / `matches` は名前に対して一致します。

### 2 つのフィルタレイヤー

フィールドは 2 つのレイヤーに分かれます。これらは `and` で組み合わせます。**`or`/`not` では
レイヤーを混在させられません** (混在させると `422` が返されます)。

**プロンプトレイヤー** (完全なツリー、すべての演算子):
`model`、`topic`、`region`、`persona`、`prompt`、`tag`。

**エンティティ / 引用レイヤー** (トップレベルの `and` リーフのみ、レポートによって異なります):

| レポート | エンティティレイヤーのフィールド |
| - | - |
| 可視性 | エンティティ (`asset`) は `filter` *ではなく* **`assets`** パラメータを使用します。 |
| 引用 | `domain` (すべての演算子、サブドメインを考慮)、`page` (すべての演算子)、`analysis_type` (`visibility`·`sentiment`·`factcheck`·`all`)、`citation_category` (`owned`·`competition`·`social`·`earned_media`·`earned_institutions`·`pr_wire`·`other`·カスタム)、`citation_tag` (カスタムタグ。`is`/`in`) |
| センチメント | `theme` / `claim`: `is`/`in`、単一の値、名前または ID。`source: "citation"` の場合: `citation_category` (`is`/`in`) と `page` (`contains_case_insensitive`、1 つの値) |
| クエリファンアウト | `analysis_type` (`visibility`·`sentiment`·`factcheck`·`all`)、`is`/`in` |
| 回答 | `analysis_type` は **プロンプトレベル** です (`visibility`·`sentiment`·`factcheck`、`is`/`in`/`not_in`、省略時はすべて)。`domain`/`page` はトップレベルの `and` リーフです: `is` で 1 つの値、`in` でリストを指定 (引用 URL の完全一致) |
| YouTube ソーシャル | `channel` がエンティティレイヤーのフィルタです。YouTube の行は既に YouTube ソースに限定されているため、`domain` と `page` は適用されません。 |

<Note>
  引用では、ドメインレポートでは `domain` で、`group_by: ["page"]` を指定した場合は
  `page` でフィルタリングします。それぞれが自身のレポートのエンティティをフィルタリングします。
</Note>

<Note>
  `source: "citation"` のセンチメントは常にページの行を返し、`group_by` を
  サポートしません。カウント対象の引用を絞り込むにはプロンプトレイヤーのフィルタを使用し、
  返されるページを絞り込むには `citation_category` または `page` を使用してください。
</Note>

<Note>
  YouTube レポートでは `channel` エンティティフィルタを使用します。`and` を使用して
  プロンプトレベルのフィルタと組み合わせることはできますが、`or` や `not` の下で組み合わせることはできません。
  YouTube の `domain` および `page` フィルタは、近似されるのではなく拒否されます。
</Note>

<Note>
  カテゴリの引用タグの一覧は [Get Citation Tags](/api-reference/organization/get-category-citation-tags) で取得できます。
  必要なタグはすべて 1 つの `in` リーフにまとめてください (値は OR で結合されます)。2 つの
  別々の `citation_tag` リーフを AND で結合したり、空のリストを渡したりすると `422` が返されます。
</Note>

## 並べ替え

サポートされている場合、`sort` は `{ "field": "<metric>", "dir": "asc" | "desc" }` です。
フィールドは、リクエストした並べ替え可能な指標 (日付でグループ化した場合は `date`) である必要があります。
**引用には `sort` がありません:** 常に引用数の多い順にランク付けされます。

## ページネーション

レスポンスは `limit` 件の行と `info.next_cursor` を返します。次のページを取得するには、そのトークンを
`cursor` として渡します。最後のページでは `next_cursor` は `null` になります。

## ストリーミング

YouTube ソーシャルレポートを除くすべてのレポートエンドポイントには、**`/stream`** バリアント
(Server-Sent Events) があります。まず `summary` イベント (`info` ブロック) が送信され、続いて行ごとに 1 つの `result`
イベントが送信されます。`limit`/`cursor` は無視され、デフォルトではすべての結果が返されます。
上限を設けるには `max_results` を指定します。センチメントのストリーミングは、ページ分割エンドポイントと同じ
ソース固有の行形式で、`source: "response"` と `source: "citation"` の両方を
受け付けます。

## レスポンス形式

すべてのレポートは `{ info, data }` を返します。

```json theme={null}
{
  "info": {
    "total_results": 8427,
    "count": 10,
    "next_cursor": "…",
    "models": ["ChatGPT", "Google Gemini", "..."],
    "start_date": "2026-06-09",
    "end_date": "2026-06-15",
    "filter": null
  },
  "data": [
    { "rank": 1, "visibility_score": 0.48 }
  ]
}
```

`info` には解決されたクエリ (対象範囲のモデル、適用されたフィルタ、日付、
ページネーション) がエコーされます。`data` は行で、指標は名前付きフィールドとして、
`group_by` のディメンションが付加された状態で含まれます。