# 查詢 Threads 個人檔案 標準 URL： https://sosoapi.ai/zh-tw/docs/api/analytics-api-threads-reads-profile-lookup 契約：sha256:11debf801a5e6096 在該連線具備確切權限時，讀取符合資格的官方公開檔案。平台的追蹤者及標準存取限制仍適用。 POST /analytics-api/threads-reads/profile-lookup ## 驗證與權限 - **接受的憑證類別：** user_session、delegated_oauth、personal_access_token - **委派能力：** agent:operate - **最低工作空間角色：** viewer - **存取範圍：** 此使用者獲准存取的資源 - **需要所有工作空間同意：** 否 - **變更狀態：** 否 - **操作完成時：** 有界官方資料或明確不可用；已授予範圍不代表已獲公開 App Review 核准 權杖只能使用其擁有者持有的權利。每次請求會檢查工作空間成員資格、資源擁有權、所選工作空間及已授予能力。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)$" }, "username": { "type": "string", "pattern": "^[A-Za-z0-9._]{1,30}$" } }, "required": [ "workspace_id", "social_account_id", "username" ], "additionalProperties": false } ``` ## 回應與完成 成功 HTTP 狀態：200 成功 HTTP 回應可能表示請求已接受，並非已完成。背景工作請儲存回傳 ID，持續檢查同一操作直到完成。已排程或已接受的貼文，只有平台確認後才算已發布；用戶端逾時無法證明結果。 ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contract_version": { "type": "string", "const": "threads-reads/v1" }, "operation": { "type": "string", "const": "profile_lookup" }, "source": { "type": "string", "const": "official_threads_api" }, "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)$" }, "provider_account_id": { "type": "string", "pattern": "^\\d{2,20}$" }, "provider_app_identity": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "oauth_snapshot_id": { "anyOf": [ { "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)$" }, { "type": "null" } ] }, "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" ] }, "unavailable_reason": { "anyOf": [ { "type": "string", "enum": [ "grant_inventory_unknown", "missing_permissions", "issuing_app_unknown", "credential_unavailable", "credential_expired", "account_unhealthy", "provider_denied", "provider_rate_limited", "provider_unavailable", "provider_response_invalid" ] }, { "type": "null" } ] }, "access": { "type": "object", "properties": { "required_permissions": { "maxItems": 4, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,99}$" } }, "missing_permissions": { "maxItems": 4, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,99}$" } }, "permission_state": { "type": "string", "enum": [ "granted", "missing", "unknown" ] }, "grant_evidence": { "type": "string", "enum": [ "exact", "unknown" ] }, "app_access": { "type": "string", "const": "unverified" } }, "required": [ "required_permissions", "missing_permissions", "permission_state", "grant_evidence", "app_access" ] }, "data": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d{2,20}$" }, "text": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9._]{1,30}$" }, { "type": "null" } ] }, "permalink": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "timestamp": { "anyOf": [ { "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)))$" }, { "type": "null" } ] }, "media_type": { "anyOf": [ { "type": "string", "enum": [ "TEXT", "TEXT_POST", "IMAGE", "VIDEO", "CAROUSEL_ALBUM", "AUDIO", "REPOST_FACADE" ] }, { "type": "null" } ] }, "is_reply": { "type": [ "boolean", "null" ] }, "is_quote_post": { "type": [ "boolean", "null" ] }, "has_replies": { "type": [ "boolean", "null" ] }, "root_post_id": { "anyOf": [ { "type": "string", "pattern": "^\\d{2,20}$" }, { "type": "null" } ] }, "replied_to_id": { "anyOf": [ { "type": "string", "pattern": "^\\d{2,20}$" }, { "type": "null" } ] } }, "required": [ "id", "text", "username", "permalink", "timestamp", "media_type", "is_reply", "is_quote_post", "has_replies" ] } }, "profile": { "anyOf": [ { "type": "object", "properties": { "username": { "type": "string", "pattern": "^[A-Za-z0-9._]{1,30}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "biography": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "is_verified": { "type": [ "boolean", "null" ] }, "follower_count": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "username", "name", "biography", "is_verified", "follower_count" ] }, { "type": "null" } ] }, "locations": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d{2,20}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "postal_code": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "id", "name", "address", "city", "country", "postal_code" ] } }, "root_post_id": { "type": "string", "pattern": "^\\d{2,20}$" }, "target_username": { "type": "string", "pattern": "^[A-Za-z0-9._]{1,30}$" }, "coverage": { "type": "object", "properties": { "complete": { "type": "boolean", "const": false }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4096 }, { "type": "null" } ] }, "omitted_rows": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reasons": { "maxItems": 8, "type": "array", "items": { "type": "string", "maxLength": 400 } } }, "required": [ "complete", "next_cursor", "omitted_rows", "reasons" ] }, "quota": { "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "const": "meta" }, "usage": { "type": "object", "properties": { "call_count": { "type": "number" }, "total_cputime": { "type": "number" }, "total_time": { "type": "number" }, "estimated_time_to_regain_access": { "type": "number" } } }, "sources": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "x-app-usage", "x-business-use-case-usage" ] } } }, "required": [ "provider", "usage", "sources" ] } } }, "required": [ "contract_version", "operation", "source", "workspace_id", "social_account_id", "provider_account_id", "provider_app_identity", "oauth_snapshot_id", "fetched_at", "status", "unavailable_reason", "access", "data", "profile", "coverage", "quota" ] } ``` ## 錯誤與安全重試 檢查 HTTP 狀態和回應內容。400 驗證錯誤可能包含 ZodError；處理常式錯誤使用 error、message 和 code 欄位。保留 request_id 或 x-request-id 以便診斷，但不要保留憑證。先解決 401/403 存取錯誤再重試，並在收到 429 時遵循 Retry-After。如寫入結果不確定或回傳 5xx，先讀取現有結果。僅在支援時重複使用冪等鍵；重試行為因操作而異，並不保證恰好傳送一次。 ## 範例 這些範例使用已依結構描述檢查的虛構值。請將 ID 替換為您有權使用的 ID、將媒體替換為已就緒素材，並將日期替換為已確認的發布時間。提交寫入前，請檢查帳號資格。本頁不會傳送 API 請求。 在伺服器上將 SOSOAPI_ACCESS_TOKEN 設為此操作接受的憑證，且不要放入瀏覽器程式碼。AI 代理程式請使用 sosoapi auth login 透過瀏覽器登入，並由 CLI 更新憑證。 request.json ```json { "workspace_id": "11111111-1111-4111-8111-111111111111", "social_account_id": "22222222-2222-4222-8222-222222222222", "username": "fictional_example" } ``` cURL ```bash curl --request POST \ "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/analytics-api/threads-reads/profile-lookup" \ -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/threads-reads/profile-lookup", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + token }, body: JSON.stringify({ "workspace_id": "11111111-1111-4111-8111-111111111111", "social_account_id": "22222222-2222-4222-8222-222222222222", "username": "fictional_example" }) }); 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/threads-reads/profile-lookup < request.json ``` 合成回應範例 ```json { "workspace_id": "11111111-1111-4111-8111-111111111111", "social_account_id": "22222222-2222-4222-8222-222222222222", "contract_version": "threads-reads/v1", "operation": "profile_lookup", "source": "official_threads_api", "provider_account_id": "12345", "provider_app_identity": null, "oauth_snapshot_id": null, "fetched_at": "2099-01-15T09:00:00Z", "status": "unavailable", "unavailable_reason": "issuing_app_unknown", "access": { "required_permissions": [ "threads_basic", "threads_profile_discovery" ], "missing_permissions": [], "permission_state": "unknown", "grant_evidence": "unknown", "app_access": "unverified" }, "data": [], "profile": null, "quota": [], "coverage": { "complete": false, "next_cursor": null, "omitted_rows": 0, "reasons": [ "Fictional documentation example: no provider request was made and no account data was read.", "App access and any pending permission review remain unverified; this is not successful provider or public-access evidence." ] } } ``` ## 相關工具與指南 MCP: sosoapi_lookup_threads_profile [API 參考](https://sosoapi.ai/zh-tw/docs/api)