# Baca sumber riset sosial publik URL kanonis: https://sosoapi.ai/id/docs/api/research-api-evidence-retrieve-social Kontrak: sha256:dadbfeb34d10743d Ambil sampel terbatas bukti sosial publik berdasarkan URL dan mutation_id; teks tidak tepercaya dan cakupannya sebagian. Memerlukan agent:research. POST /research-api/evidence/retrieve-social ## Autentikasi dan izin - **Jenis kredensial yang diterima:** user_session, delegated_oauth, personal_access_token - **Kemampuan yang didelegasikan:** agent:research - **Peran ruang kerja minimum:** editor - **Cakupan akses:** Sumber daya yang boleh diakses pengguna ini - **Persetujuan seluruh ruang kerja diperlukan:** Tidak - **Mengubah status:** Ya - **Saat operasi selesai:** Tanda terima sosial terbatas yang tersimpan secara permanen dan referensi bukti yang tepat; sampel sebagian dan penghitung yang tidak diketahui tetap dinyatakan jelas Token hanya dapat menggunakan hak pemiliknya. Setiap permintaan memeriksa keanggotaan ruang kerja, kepemilikan sumber daya, ruang kerja terpilih, dan kemampuan yang diberikan. Profil core dan full mengubah alat yang ditampilkan; tidak memberikan akses. ## Kolom permintaan ```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)$" }, "mutation_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)$" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "workspace_id", "mutation_id", "url" ], "additionalProperties": false } ``` ## Respons dan penyelesaian Status HTTP berhasil: 200 Respons HTTP berhasil dapat berarti permintaan diterima, bukan selesai. Untuk pekerjaan latar belakang, simpan ID yang dikembalikan dan periksa operasi yang sama sampai selesai. Postingan terjadwal atau diterima baru dipublikasikan setelah platform mengonfirmasi; timeout klien tidak membuktikan hasilnya. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "retrieval": { "type": "object", "properties": { "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)$" }, "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)$" }, "mutation_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)$" }, "kind": { "type": "string", "const": "public_social" }, "state": { "type": "string", "enum": [ "pending", "running", "completed", "cancelled", "unconfirmed", "expired" ] }, "created_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" }, "settled_at": { "anyOf": [ { "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" }, { "type": "null" } ] }, "valid_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" }, "result": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "facebook_public_web", "instagram_public_web", "threads_public_web" ] }, "platform": { "type": "string", "enum": [ "facebook", "instagram", "threads" ] }, "canonical_url": { "type": "string", "maxLength": 2048, "format": "uri" }, "fetched_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" }, "expires_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" }, "upstream_updated_at": { "type": "null" }, "status": { "type": "string", "enum": [ "available", "partial", "unavailable" ] }, "profile": { "anyOf": [ { "type": "object", "properties": { "source_account_id": { "type": "string", "pattern": "^[0-9]{1,30}$" }, "id_namespace": { "type": "string", "const": "public_web" }, "username": { "type": "string", "minLength": 1, "maxLength": 50 }, "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "followers": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "source_account_id", "id_namespace", "username", "name", "followers" ] }, { "type": "null" } ] }, "posts": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "source_post_id": { "type": "string", "pattern": "^[0-9]{1,30}$" }, "id_namespace": { "type": "string", "const": "public_web" }, "shortcode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "source_account_id": { "type": "string", "pattern": "^[0-9]{1,30}$" }, "author": { "type": "string", "minLength": 1, "maxLength": 50 }, "canonical_url": { "type": "string", "maxLength": 2048, "format": "uri" }, "text": { "type": "string", "maxLength": 30000 }, "published_at": { "anyOf": [ { "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" }, { "type": "null" } ] }, "media_kind": { "type": "string", "enum": [ "text", "image", "video", "carousel", "unknown" ] }, "metrics": { "type": "object", "properties": { "likes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "comments": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "reactions": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "shares": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "views": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "likes", "comments", "reactions", "shares", "views" ] } }, "required": [ "source_post_id", "id_namespace", "shortcode", "source_account_id", "author", "canonical_url", "text", "published_at", "media_kind", "metrics" ] } }, "coverage": { "type": "object", "properties": { "complete": { "type": "boolean", "const": false }, "reasons": { "maxItems": 20, "type": "array", "items": { "type": "string", "enum": [ "initial_page_only", "public_web_ids", "metrics_unavailable", "profile_only", "no_attributable_posts", "foreign_or_malformed_rows", "parser_limit", "unsupported_payload", "blocked", "rate_limited", "upstream_http_error", "redirect_rejected", "unsupported_content_type", "response_too_large", "timeout", "aborted", "network_error", "inconsistent_identity", "research_limit", "source_removed" ] } }, "omitted_rows": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "next_cursor": { "type": "null" } }, "required": [ "complete", "reasons", "omitted_rows", "next_cursor" ] } }, "required": [ "source", "platform", "canonical_url", "fetched_at", "expires_at", "upstream_updated_at", "status", "profile", "posts", "coverage" ] }, { "type": "null" } ] }, "evidence": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "evidence_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)$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "evidence_id", "revision" ] } } }, "required": [ "id", "workspace_id", "mutation_id", "kind", "state", "created_at", "settled_at", "valid_until", "result", "evidence" ] } }, "required": [ "retrieval" ] } ``` ## Kesalahan dan percobaan ulang aman Periksa status HTTP dan isi respons. Kesalahan validasi 400 mungkin berisi ZodError; kesalahan handler menggunakan kolom error, message, dan code. Simpan request_id atau x-request-id untuk diagnosis, tanpa kredensial. Atasi kesalahan akses 401/403 sebelum mencoba lagi, dan ikuti Retry-After untuk 429. Jika penulisan belum pasti atau mengembalikan 5xx, baca hasil yang sudah ada terlebih dahulu. Gunakan kembali kunci idempotensi hanya jika didukung; perilaku percobaan ulang berbeda menurut operasi dan tidak menjamin pengiriman tepat satu kali. ## Contoh Contoh ini menggunakan nilai fiktif yang diperiksa terhadap skema. Ganti ID dengan yang diizinkan bagi Anda, media dengan aset siap, dan tanggal dengan waktu publikasi yang dikonfirmasi. Periksa kelayakan akun sebelum mengirim penulisan. Halaman ini tidak mengirim permintaan API. Atur SOSOAPI_ACCESS_TOKEN di server Anda ke kredensial yang diterima operasi ini, dan jauhkan dari kode browser. Untuk agen AI, gunakan sosoapi auth login untuk masuk melalui browser dan biarkan CLI memperbarui kredensialnya. request.json ```json { "workspace_id": "11111111-1111-4111-8111-111111111111", "mutation_id": "40000000-0000-4000-8000-000000000005", "url": "https://www.instagram.com/fictional_example/" } ``` cURL ```bash curl --request POST \ "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/research-api/evidence/retrieve-social" \ -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/research-api/evidence/retrieve-social", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + token }, body: JSON.stringify({ "workspace_id": "11111111-1111-4111-8111-111111111111", "mutation_id": "40000000-0000-4000-8000-000000000005", "url": "https://www.instagram.com/fictional_example/" }) }); const result = await response.json(); // Check response.ok, the operation-specific body and completion state before continuing. ``` CLI ```bash # This operation requires a CLI build containing the updated Research contract. # Use HTTP or hosted MCP if your CLI build does not include it. # 此操作需要包含更新版 Research contract 的 CLI build。 # 如 CLI build 未包含此 contract，請使用 HTTP 或 hosted MCP。 npx sosoapi api post /research-api/evidence/retrieve-social < request.json ``` Contoh respons sintetis ```json { "retrieval": { "id": "30000000-0000-4000-8000-000000000007", "workspace_id": "11111111-1111-4111-8111-111111111111", "mutation_id": "40000000-0000-4000-8000-000000000005", "kind": "public_social", "state": "completed", "created_at": "2099-01-15T09:00:00Z", "settled_at": "2099-01-15T09:00:01Z", "valid_until": "2099-01-16T09:00:00Z", "evidence": [], "result": { "source": "instagram_public_web", "platform": "instagram", "canonical_url": "https://www.instagram.com/fictional_example/", "fetched_at": "2099-01-15T09:00:00Z", "expires_at": "2099-01-16T09:00:00Z", "upstream_updated_at": null, "status": "unavailable", "profile": null, "posts": [], "coverage": { "complete": false, "reasons": [ "blocked" ], "omitted_rows": 0, "next_cursor": null } } } } ``` ## Alat dan panduan terkait MCP: sosoapi_research_evidence_retrieve-social [Referensi API](https://sosoapi.ai/id/docs/api)