研究及帶來源簡報
讀取研究收集歷史
從精確已選語料定位目前獲授權的同一 Listening 串流、query revision、generation 及實際方法，按 UTC 小時或日讀取最多七日、24 格的採集觀察。筆記另列排除數，缺漏是未知而非零；部分 HN 樣本不可當作市場增長、動量或預測。
POST /research-api/collection-history/queryContract 核對日期: · sha256:ab393e91e9b7f18a
概覽
從精確已選語料定位目前獲授權的同一 Listening 串流、query revision、generation 及實際方法，按 UTC 小時或日讀取最多七日、24 格的採集觀察。筆記另列排除數，缺漏是未知而非零；部分 HN 樣本不可當作市場增長、動量或預測。
HTTP 成功只表示本次操作的回應。背景工作須保留回傳 ID，並讀取同一操作，直至達到文件指定的終態。接受請求、排程成功或客戶端逾時，均不代表已發佈。
驗證及權限
憑證不能擴大持有人的權限。實際操作仍會檢查工作空間成員資格、資源擁有權、已選工作空間及能力授權。Tool profile 只會改變可見工具，不會授予權限。
請求欄位
必填表示在所屬物件及所選分支內必須提供；子欄位必填不代表可選的父物件亦變成必填。以下欄位名稱及規則直接來自 contract。
| 欄位／分支 | 類型／必填 | 限制 |
|---|---|---|
$ | 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，並讀取同一操作，直至達到文件指定的終態。接受請求、排程成功或客戶端逾時，均不代表已發佈。
必填表示在所屬物件及所選分支內必須提供；子欄位必填不代表可選的父物件亦變成必填。以下欄位名稱及規則直接來自 contract。
| 欄位／分支 | 類型／必填 | 限制 |
|---|---|---|
$ | 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；handler 錯誤可能採用 error／message／code envelope。請保留可用的 request_id 或 x-request-id，避免記錄憑證。遇到 401／403 時，須先修正存取問題；429 須遵守 Retry-After。寫入結果未明或回傳 5xx 時，請先讀取原有結果，再決定是否重試。只有操作支援時才可重用 idempotency key；並無通用重試或 exactly-once 保證。
問題排解指南範例
以下虛構值已按 contract 驗證，並非真實帳戶 ID、憑證或發佈紀錄。請以已授權範圍回傳的 ID、已準備完成的素材及已審核排程取代，並在寫入前核對平台資格。此頁不會呼叫 API。
在伺服器環境設定 SOSOAPI_ACCESS_TOKEN，使用此操作接受的憑證。請勿將憑證放入瀏覽器程式。一般 AI Agent 建議透過 sosoapi auth login 使用瀏覽器 OAuth，由 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"
}
]
}