# プロバイダーインサイトをリクエスト

正規URL： https://sosoapi.ai/ja/docs/api/analytics-api-provider-insights-request

契約: sha256:563d2d581da0ad29

アカウントまたは一つの投稿について、任意の日付範囲（最大366日）のインサイトをプロバイダーに要求します。request_idを返し、キャッシュがあれば結果も返します。それ以外はsosoapi_get_provider_insight_statusで確認してください。

POST /analytics-api/provider-insights/request

## 認証と権限

- **受け付ける認証情報の種類:** user_session, delegated_oauth, personal_access_token

- **委任された機能権限:** agent:operate

- **ワークスペースの最低ロール:** viewer

- **アクセス範囲:** このユーザーがアクセスを許可されたリソース

- **すべてのワークスペースへの同意が必要:** いいえ

- **状態を変更:** いいえ

- **操作完了時：** プロバイダー固有の結果、または取得できない明確な理由

トークンは所有者の権利内でのみ使えます。各要求で所属、リソース所有権、選択ワークスペース、付与機能を確認します。coreとfullは表示だけを変え、アクセスは付与しません。

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

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "social_account_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "resource_kind": {
      "type": "string",
      "enum": [
        "account",
        "post"
      ]
    },
    "provider_resource_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "include_audience": {
      "type": "boolean"
    },
    "refresh": {
      "type": "boolean"
    }
  },
  "required": [
    "workspace_id",
    "social_account_id",
    "resource_kind"
  ],
  "additionalProperties": false
}
```

## レスポンスと完了条件

成功時のHTTPステータス： 200, 202

HTTP成功は完了ではなく受理の場合があります。バックグラウンド処理はIDを保存し、同じ処理を完了まで確認します。予約・受理された投稿はプラットフォーム確認後のみ公開済みです。タイムアウトだけでは結果を判断できません。

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "contract_version": {
      "type": "string",
      "const": "provider-insights/v1"
    },
    "request_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "completed"
      ]
    },
    "cache_status": {
      "type": "string",
      "enum": [
        "hit",
        "miss",
        "bypassed"
      ]
    },
    "poll_after_ms": {
      "type": "integer",
      "minimum": 0,
      "maximum": 60000
    },
    "result": {
      "type": "object",
      "properties": {
        "contract_version": {
          "type": "string",
          "const": "provider-insights/v1"
        },
        "request_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "platform": {
          "type": "string",
          "enum": [
            "facebook",
            "instagram",
            "threads",
            "youtube"
          ]
        },
        "resource": {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "account",
                "post"
              ]
            },
            "social_account_id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            "provider_resource_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "kind",
            "social_account_id",
            "provider_resource_id"
          ]
        },
        "provider_api_version": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "fetched_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "status": {
          "type": "string",
          "enum": [
            "available",
            "partial",
            "unavailable"
          ]
        },
        "availability": {
          "minItems": 1,
          "maxItems": 64,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "scope": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "status": {
                "type": "string",
                "enum": [
                  "available",
                  "partial",
                  "not_returned",
                  "unsupported",
                  "permission_required",
                  "threshold_not_met",
                  "no_data",
                  "failed"
                ]
              },
              "reason": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              }
            },
            "required": [
              "scope",
              "status"
            ]
          }
        },
        "provider_data": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ]
        },
        "requested_date_range": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "start_date": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                },
                "end_date": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                }
              },
              "required": [
                "start_date",
                "end_date"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "cache": {
          "type": "object",
          "properties": {
            "authoritative": {
              "type": "boolean",
              "const": false
            },
            "status": {
              "type": "string",
              "enum": [
                "stored",
                "hit",
                "bypassed"
              ]
            },
            "expires_at": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            }
          },
          "required": [
            "authoritative",
            "status",
            "expires_at"
          ]
        }
      },
      "required": [
        "contract_version",
        "request_id",
        "platform",
        "resource",
        "provider_api_version",
        "fetched_at",
        "status",
        "availability",
        "provider_data",
        "requested_date_range",
        "cache"
      ]
    }
  },
  "required": [
    "contract_version",
    "request_id",
    "status",
    "cache_status",
    "poll_after_ms"
  ]
}
```

## エラーと安全な再試行

HTTPステータスとレスポンス本文を確認します。400の検証エラーにはZodErrorが含まれる場合があります。ハンドラーエラーはerror、message、codeを使用します。診断用にrequest_idまたはx-request-idを保持し、認証情報は含めないでください。401/403はアクセス問題を解消してから再試行し、429はRetry-Afterに従います。書き込み結果が不確か、または5xxの場合は、まず既存の結果を取得してください。冪等性キーは対応する操作でのみ再利用します。再試行の挙動は操作ごとに異なり、厳密に一回の配信は保証しません。

## 例

スキーマ確認済みの架空値の例です。認可されたID、準備済みメディア、確認済みの公開日時に置き換え、書き込み前に適格性を確認してください。このページはAPIを呼びません。

サーバーのSOSOAPI_ACCESS_TOKENに操作が受け付ける認証情報を設定し、ブラウザーコードに含めないでください。エージェントはsosoapi auth loginでブラウザーログインし、CLIに更新を任せます。

request.json

```json
{
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "social_account_id": "11111111-1111-4111-8111-111111111111",
  "resource_kind": "account"
}
```

cURL

```bash
curl --request POST \
  "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/analytics-api/provider-insights/request" \
  -H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
```

JavaScript

```js
// Server-side JavaScript. Do not print tokens or credential-bearing responses.
const token = process.env.SOSOAPI_ACCESS_TOKEN;
if (!token) throw new Error("Set an accepted credential for this operation");
const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/analytics-api/provider-insights/request", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
  body: JSON.stringify({
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "social_account_id": "11111111-1111-4111-8111-111111111111",
  "resource_kind": "account"
})
});
const result = await response.json();
// Check response.ok, the operation-specific body and completion state before continuing.
```

CLI

```bash
npx sosoapi api post /analytics-api/provider-insights/request < request.json
```

合成レスポンス例

```json
{
  "contract_version": "provider-insights/v1",
  "request_id": "11111111-1111-4111-8111-111111111111",
  "status": "queued",
  "cache_status": "hit",
  "poll_after_ms": 0
}
```

## 関連ツールとガイド

MCP: sosoapi_request_provider_insights

[APIリファレンス](https://sosoapi.ai/ja/docs/api)