研究と引用付きブリーフ
研究収集履歴を読む
限定的な UTC コホート観測を読みます。不明はゼロではありません。部分的な HN サンプルは勢いや予測の判断に適しません。agent:research が必要です。
POST /research-api/collection-history/query契約確認日： · sha256:ab393e91e9b7f18a
概要
限定的な UTC コホート観測を読みます。不明はゼロではありません。部分的な HN サンプルは勢いや予測の判断に適しません。agent:research が必要です。
HTTP成功は完了ではなく受理の場合があります。バックグラウンド処理はIDを保存し、同じ処理を完了まで確認します。予約・受理された投稿はプラットフォーム確認後のみ公開済みです。タイムアウトだけでは結果を判断できません。
認証と権限
トークンは所有者の権利内でのみ使えます。各要求で所属、リソース所有権、選択ワークスペース、付与機能を確認します。coreとfullは表示だけを変え、アクセスは付与しません。
リクエストのフィールド
必須とは、親オブジェクトと選択分岐内で必須という意味です。必須の子があっても任意の親は必須になりません。以下のルールとフィールド名は契約から転記しています。
| フィールド／分岐 | 型／必須 | 制約 |
|---|---|---|
$ | object親要素内で必須 |
|
workspace_id | string親要素内で必須 |
|
project_id | string親要素内で必須 |
|
project_revision | integer親要素内で必須 |
|
corpus_snapshot_id | string親要素内で必須 |
|
bucket | string任意／項目 |
|
since | string親要素内で必須 |
|
until | string親要素内で必須 |
|
完全なJSON Schema
{
"$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)$"
},
"project_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)$"
},
"project_revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"corpus_snapshot_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)$"
},
"bucket": {
"default": "day",
"type": "string",
"enum": [
"hour",
"day"
]
},
"since": {
"type": "string",
"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)))$",
"format": "date-time"
},
"until": {
"type": "string",
"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)))$",
"format": "date-time"
}
},
"required": [
"workspace_id",
"project_id",
"project_revision",
"corpus_snapshot_id",
"since",
"until"
],
"additionalProperties": false
}レスポンスと完了条件
成功時のHTTPステータス： 200. 操作完了時： current authorized aggregate collection history for one exact source cohort; collection counts are not publication volume, market growth, momentum or forecasts.
HTTP成功は完了ではなく受理の場合があります。バックグラウンド処理はIDを保存し、同じ処理を完了まで確認します。予約・受理された投稿はプラットフォーム確認後のみ公開済みです。タイムアウトだけでは結果を判断できません。
必須とは、親オブジェクトと選択分岐内で必須という意味です。必須の子があっても任意の親は必須になりません。以下のルールとフィールド名は契約から転記しています。
| フィールド／分岐 | 型／必須 | 制約 |
|---|---|---|
$ | object親要素内で必須 | — |
workspace_id | string親要素内で必須 |
|
project_id | string親要素内で必須 |
|
project_revision | integer親要素内で必須 |
|
corpus_snapshot_id | string親要素内で必須 |
|
bucket | string親要素内で必須 |
|
since | string親要素内で必須 |
|
until | string親要素内で必須 |
|
generated_at | string親要素内で必須 |
|
status | string親要素内で必須 |
|
reason | string | null親要素内で必須 | — |
reasonanyOf 1 | string親要素内で必須 |
|
reasonanyOf 2 | null親要素内で必須 | — |
cohort | object | null親要素内で必須 | — |
cohortanyOf 1 | object親要素内で必須 | — |
cohort.sourceanyOf 1 | string親要素内で必須 |
|
cohort.query_revisionanyOf 1 | integer親要素内で必須 |
|
cohort.generationanyOf 1 | integer親要素内で必須 |
|
cohort.method_versionanyOf 1 | string親要素内で必須 |
|
cohort.selected_listening_refsanyOf 1 | integer親要素内で必須 |
|
cohort.excluded_selected_itemsanyOf 1 | integer親要素内で必須 |
|
cohort.scopeanyOf 1 | string親要素内で必須 |
|
cohortanyOf 2 | null親要素内で必須 | — |
method_version | string親要素内で必須 |
|
time_basis | string親要素内で必須 |
|
deduplication | string親要素内で必須 |
|
count_meaning | string親要素内で必須 |
|
momentum_eligible | boolean親要素内で必須 |
|
forecast_eligible | boolean親要素内で必須 |
|
qualification_reason | string親要素内で必須 |
|
observed_bins | integer親要素内で必須 |
|
unknown_bins | integer親要素内で必須 |
|
bins | array親要素内で必須 |
|
bins[] | object任意／項目 | — |
bins[].start | string親要素内で必須 |
|
bins[].end | string親要素内で必須 |
|
bins[].period_partial | boolean親要素内で必須 | — |
bins[].state | string親要素内で必須 |
|
bins[].counts | object | null親要素内で必須 | — |
bins[].countsanyOf 1 | object親要素内で必須 | — |
bins[].counts.source_itemsanyOf 1 | integer親要素内で必須 |
|
bins[].counts.matched_itemsanyOf 1 | integer親要素内で必須 |
|
bins[].counts.removed_itemsanyOf 1 | integer親要素内で必須 |
|
bins[].counts.unavailable_itemsanyOf 1 | integer親要素内で必須 |
|
bins[].countsanyOf 2 | null親要素内で必須 | — |
bins[].runs | object親要素内で必須 | — |
bins[].runs.total | integer親要素内で必須 |
|
bins[].runs.completed | integer親要素内で必須 |
|
bins[].runs.successful | integer親要素内で必須 |
|
bins[].runs.succeeded | integer親要素内で必須 |
|
bins[].runs.partial | integer親要素内で必須 |
|
bins[].runs.failed | integer親要素内で必須 |
|
bins[].runs.cancelled | integer親要素内で必須 |
|
bins[].runs.pending | integer親要素内で必須 |
|
bins[].source_windows | object | null親要素内で必須 | — |
bins[].source_windowsanyOf 1 | object親要素内で必須 | — |
bins[].source_windows.sinceanyOf 1 | string親要素内で必須 |
|
bins[].source_windows.untilanyOf 1 | string親要素内で必須 |
|
bins[].source_windows.distinct_windowsanyOf 1 | integer親要素内で必須 |
|
bins[].source_windowsanyOf 2 | null親要素内で必須 | — |
bins[].gaps | array親要素内で必須 |
|
bins[].gaps[] | string任意／項目 |
|
bins[].coverage | string親要素内で必須 |
|
完全なJSON Schema
{
"$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)$"
},
"project_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)$"
},
"project_revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"corpus_snapshot_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)$"
},
"bucket": {
"type": "string",
"enum": [
"hour",
"day"
]
},
"since": {
"type": "string",
"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)))$",
"format": "date-time"
},
"until": {
"type": "string",
"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)))$",
"format": "date-time"
},
"generated_at": {
"type": "string",
"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)))$",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"available",
"insufficient_history",
"not_applicable",
"incomparable"
]
},
"reason": {
"anyOf": [
{
"type": "string",
"enum": [
"no_listening_sources",
"mixed_sources",
"mixed_cohorts",
"mixed_methods",
"method_unavailable",
"unsupported_method",
"no_completed_observations",
"history_limit"
]
},
{
"type": "null"
}
]
},
"cohort": {
"anyOf": [
{
"type": "object",
"properties": {
"source": {
"type": "string",
"const": "hacker_news"
},
"query_revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"generation": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"method_version": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"selected_listening_refs": {
"type": "integer",
"minimum": 1,
"maximum": 500
},
"excluded_selected_items": {
"type": "integer",
"minimum": 0,
"maximum": 499
},
"scope": {
"type": "string",
"const": "selected_listening_stream_cohort"
}
},
"required": [
"source",
"query_revision",
"generation",
"method_version",
"selected_listening_refs",
"excluded_selected_items",
"scope"
]
},
{
"type": "null"
}
]
},
"method_version": {
"type": "string",
"const": "listening-collection-history/v1"
},
"time_basis": {
"type": "string",
"const": "collection_completed_at_or_requested_at"
},
"deduplication": {
"type": "string",
"const": "latest_observation_per_source_per_bin"
},
"count_meaning": {
"type": "string",
"const": "bounded_collection_observations"
},
"momentum_eligible": {
"type": "boolean",
"const": false
},
"forecast_eligible": {
"type": "boolean",
"const": false
},
"qualification_reason": {
"type": "string",
"enum": [
"hn_partial_overlapping_sample_unqualified",
"no_qualified_cohort"
]
},
"observed_bins": {
"type": "integer",
"minimum": 0,
"maximum": 24
},
"unknown_bins": {
"type": "integer",
"minimum": 0,
"maximum": 24
},
"bins": {
"maxItems": 24,
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "string",
"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)))$",
"format": "date-time"
},
"end": {
"type": "string",
"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)))$",
"format": "date-time"
},
"period_partial": {
"type": "boolean"
},
"state": {
"type": "string",
"enum": [
"observed",
"unknown"
]
},
"counts": {
"anyOf": [
{
"type": "object",
"properties": {
"source_items": {
"type": "integer",
"minimum": 0,
"maximum": 10240
},
"matched_items": {
"type": "integer",
"minimum": 0,
"maximum": 10240
},
"removed_items": {
"type": "integer",
"minimum": 0,
"maximum": 10240
},
"unavailable_items": {
"type": "integer",
"minimum": 0,
"maximum": 10240
}
},
"required": [
"source_items",
"matched_items",
"removed_items",
"unavailable_items"
]
},
{
"type": "null"
}
]
},
"runs": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"maximum": 512
},
"completed": {
"type": "integer",
"minimum": 0,
"maximum": 512
},
"successful": {
"type": "integer",
"minimum": 0,
"maximum": 512
},
"succeeded": {
"type": "integer",
"minimum": 0,
"maximum": 512
},
"partial": {
"type": "integer",
"minimum": 0,
"maximum": 512
},
"failed": {
"type": "integer",
"minimum": 0,
"maximum": 512
},
"cancelled": {
"type": "integer",
"minimum": 0,
"maximum": 512
},
"pending": {
"type": "integer",
"minimum": 0,
"maximum": 512
}
},
"required": [
"total",
"completed",
"successful",
"succeeded",
"partial",
"failed",
"cancelled",
"pending"
]
},
"source_windows": {
"anyOf": [
{
"type": "object",
"properties": {
"since": {
"type": "string",
"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)))$",
"format": "date-time"
},
"until": {
"type": "string",
"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)))$",
"format": "date-time"
},
"distinct_windows": {
"type": "integer",
"minimum": 1,
"maximum": 512
}
},
"required": [
"since",
"until",
"distinct_windows"
]
},
{
"type": "null"
}
]
},
"gaps": {
"maxItems": 5,
"type": "array",
"items": {
"type": "string",
"enum": [
"unobserved",
"incomplete_collection",
"failed_collection",
"cancelled_collection",
"partial_period"
]
}
},
"coverage": {
"type": "string",
"const": "partial_indexed_sample"
}
},
"required": [
"start",
"end",
"period_partial",
"state",
"counts",
"runs",
"source_windows",
"gaps",
"coverage"
]
}
}
},
"required": [
"workspace_id",
"project_id",
"project_revision",
"corpus_snapshot_id",
"bucket",
"since",
"until",
"generated_at",
"status",
"reason",
"cohort",
"method_version",
"time_basis",
"deduplication",
"count_meaning",
"momentum_eligible",
"forecast_eligible",
"qualification_reason",
"observed_bins",
"unknown_bins",
"bins"
]
}エラーと安全な再試行
HTTPステータスとレスポンス本文を確認します。400の検証エラーにはZodErrorが含まれる場合があります。ハンドラーエラーはerror、message、codeを使用します。診断用にrequest_idまたはx-request-idを保持し、認証情報は含めないでください。401/403はアクセス問題を解消してから再試行し、429はRetry-Afterに従います。書き込み結果が不確か、または5xxの場合は、まず既存の結果を取得してください。冪等性キーは対応する操作でのみ再利用します。再試行の挙動は操作ごとに異なり、厳密に一回の配信は保証しません。
トラブルシューティングガイド例
スキーマ確認済みの架空値の例です。認可されたID、準備済みメディア、確認済みの公開日時に置き換え、書き込み前に適格性を確認してください。このページはAPIを呼びません。
サーバーのSOSOAPI_ACCESS_TOKENに操作が受け付ける認証情報を設定し、ブラウザーコードに含めないでください。AIエージェントはsosoapi auth loginでブラウザーログインし、CLIに更新を任せます。
request.json
{
"workspace_id": "11111111-1111-4111-8111-111111111111",
"project_id": "30000000-0000-4000-8000-000000000001",
"project_revision": 1,
"corpus_snapshot_id": "30000000-0000-4000-8000-000000000002",
"bucket": "day",
"since": "2026-11-01T00:00:00Z",
"until": "2026-11-02T00:00:00Z"
}cURL
curl --request POST \
"https://gqeshlawtcexsapabaui.supabase.co/functions/v1/research-api/collection-history/query" \
-H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @request.jsonJavaScript
// 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/research-api/collection-history/query", {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
body: JSON.stringify({
"workspace_id": "11111111-1111-4111-8111-111111111111",
"project_id": "30000000-0000-4000-8000-000000000001",
"project_revision": 1,
"corpus_snapshot_id": "30000000-0000-4000-8000-000000000002",
"bucket": "day",
"since": "2026-11-01T00:00:00Z",
"until": "2026-11-02T00:00:00Z"
})
});
const result = await response.json();
// Check response.ok, the operation-specific body and completion state before continuing.CLI
npx sosoapi api post /research-api/collection-history/query < request.json合成レスポンス例
{
"workspace_id": "11111111-1111-4111-8111-111111111111",
"project_id": "30000000-0000-4000-8000-000000000001",
"project_revision": 1,
"corpus_snapshot_id": "30000000-0000-4000-8000-000000000002",
"bucket": "day",
"since": "2026-11-01T00:00:00Z",
"until": "2026-11-02T00:00:00Z",
"generated_at": "2026-11-03T00:00:00Z",
"status": "insufficient_history",
"reason": "no_completed_observations",
"cohort": {
"source": "hacker_news",
"query_revision": 1,
"generation": 1,
"method_version": "hn-indexed-literal-sample/v1",
"selected_listening_refs": 1,
"excluded_selected_items": 0,
"scope": "selected_listening_stream_cohort"
},
"method_version": "listening-collection-history/v1",
"time_basis": "collection_completed_at_or_requested_at",
"deduplication": "latest_observation_per_source_per_bin",
"count_meaning": "bounded_collection_observations",
"momentum_eligible": false,
"forecast_eligible": false,
"qualification_reason": "hn_partial_overlapping_sample_unqualified",
"observed_bins": 0,
"unknown_bins": 1,
"bins": [
{
"start": "2026-11-01T00:00:00Z",
"end": "2026-11-02T00:00:00Z",
"period_partial": false,
"state": "unknown",
"counts": null,
"runs": {
"total": 0,
"completed": 0,
"successful": 0,
"succeeded": 0,
"partial": 0,
"failed": 0,
"cancelled": 0,
"pending": 0
},
"source_windows": null,
"gaps": [
"unobserved"
],
"coverage": "partial_indexed_sample"
}
]
}