البحث والموجزات الموثقة بالمراجع

قراءة مصدر بحث اجتماعي عام

جلب عينة محدودة من الأدلة الاجتماعية العامة باستخدام URL و mutation_id؛ النص غير موثوق والتغطية جزئية. يتطلب agent:research.

POST /research-api/evidence/retrieve-social

مراجعة العقد: 2026-11-03 · sha256:dadbfeb34d10743d

اقرأ بصيغة Markdown تنزيل العقد العام تنزيل OpenAPI

نظرة عامة

قد يعني نجاح HTTP قبول الطلب لا اكتماله. للعمل الخلفي، احفظ المعرّف المُعاد وتابع العملية نفسها حتى تنتهي. لا يُعدّ المنشور المجدول أوالمقبول منشوراً حتى تأكيد المنصة؛ انتهاء مهلة العميل لا يثبت النتيجة.

المصادقة والأذونات

فئات بيانات الاعتماد المقبولة: user_session, delegated_oauth, personal_access_token
إمكانية مفوّضة: agent:research
الحد الأدنى لدور مساحة العمل: editor
نطاق الوصول: الموارد التي يحق لهذا المستخدم الوصول إليها
تلزم موافقة تشمل جميع مساحات العمل: لا
يغيّر الحالة: نعم
متى تُعدّ العملية مكتملة: durable bounded social receipt and exact evidence references; partial samples and unknown counters stay explicit

لا يستخدم الرمز إلا حقوق مالكه. يفحص كل طلب عضوية مساحة العمل وملكية المورد والمساحات المحددة والإمكانات الممنوحة. يغيّر core و full الأدوات المعروضة؛ ولا يمنحان وصولاً.

حقول الطلب

تعني «مطلوب» داخل الكائن الأب والفرع المختار. الحقل الابن المطلوب لا يجعل الأب الاختياري مطلوباً. نُسخت القواعد وأسماء الحقول أدناه من العقد.

حقول الطلب
الحقل / الفرع	النوع / مطلوب	القيود
`$`	`object`مطلوب في العنصر الأب	`additionalProperties: false`
`workspace_id`	`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`	`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`	`string`مطلوب في العنصر الأب	`format: "uri"` `maxLength: 2048`

مخطط 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)$"
    },
    "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
}

الاستجابة والاكتمال

رموز نجاح HTTP: 200. عندما تكتمل العملية: durable bounded social receipt and exact evidence references; partial samples and unknown counters stay explicit.

الاستجابة والاكتمال
الحقل / الفرع	النوع / مطلوب	القيود
`$`	`object`مطلوب في العنصر الأب	—
`retrieval`	`object`مطلوب في العنصر الأب	—
`retrieval.id`	`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)$"`
`retrieval.workspace_id`	`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)$"`
`retrieval.mutation_id`	`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)$"`
`retrieval.kind`	`string`مطلوب في العنصر الأب	`const: "public_social"`
`retrieval.state`	`string`مطلوب في العنصر الأب	`enum: ["pending","running","completed","cancelled","unconfirmed","expired"]`
`retrieval.created_at`	`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)))$"`
`retrieval.settled_at`	`string \| null`مطلوب في العنصر الأب	—
`retrieval.settled_at`anyOf 1	`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)))$"`
`retrieval.settled_at`anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.valid_until`	`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)))$"`
`retrieval.result`	`object \| null`مطلوب في العنصر الأب	—
`retrieval.result`anyOf 1	`object`مطلوب في العنصر الأب	—
`retrieval.result.source`anyOf 1	`string`مطلوب في العنصر الأب	`enum: ["facebook_public_web","instagram_public_web","threads_public_web"]`
`retrieval.result.platform`anyOf 1	`string`مطلوب في العنصر الأب	`enum: ["facebook","instagram","threads"]`
`retrieval.result.canonical_url`anyOf 1	`string`مطلوب في العنصر الأب	`format: "uri"` `maxLength: 2048`
`retrieval.result.fetched_at`anyOf 1	`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)))$"`
`retrieval.result.expires_at`anyOf 1	`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)))$"`
`retrieval.result.upstream_updated_at`anyOf 1	`null`مطلوب في العنصر الأب	—
`retrieval.result.status`anyOf 1	`string`مطلوب في العنصر الأب	`enum: ["available","partial","unavailable"]`
`retrieval.result.profile`anyOf 1	`object \| null`مطلوب في العنصر الأب	—
`retrieval.result.profile`anyOf 1 / anyOf 1	`object`مطلوب في العنصر الأب	—
`retrieval.result.profile.source_account_id`anyOf 1 / anyOf 1	`string`مطلوب في العنصر الأب	`pattern: "^[0-9]{1,30}$"`
`retrieval.result.profile.id_namespace`anyOf 1 / anyOf 1	`string`مطلوب في العنصر الأب	`const: "public_web"`
`retrieval.result.profile.username`anyOf 1 / anyOf 1	`string`مطلوب في العنصر الأب	`minLength: 1` `maxLength: 50`
`retrieval.result.profile.name`anyOf 1 / anyOf 1	`string \| null`مطلوب في العنصر الأب	—
`retrieval.result.profile.name`anyOf 1 / anyOf 1 / anyOf 1	`string`مطلوب في العنصر الأب	`minLength: 1` `maxLength: 200`
`retrieval.result.profile.name`anyOf 1 / anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.profile.followers`anyOf 1 / anyOf 1	`integer \| null`مطلوب في العنصر الأب	—
`retrieval.result.profile.followers`anyOf 1 / anyOf 1 / anyOf 1	`integer`مطلوب في العنصر الأب	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.profile.followers`anyOf 1 / anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.profile`anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.posts`anyOf 1	`array`مطلوب في العنصر الأب	`maxItems: 20`
`retrieval.result.posts[]`anyOf 1	`object`اختياري / عنصر	—
`retrieval.result.posts[].source_post_id`anyOf 1	`string`مطلوب في العنصر الأب	`pattern: "^[0-9]{1,30}$"`
`retrieval.result.posts[].id_namespace`anyOf 1	`string`مطلوب في العنصر الأب	`const: "public_web"`
`retrieval.result.posts[].shortcode`anyOf 1	`string \| null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].shortcode`anyOf 1 / anyOf 1	`string`مطلوب في العنصر الأب	`minLength: 1` `maxLength: 64`
`retrieval.result.posts[].shortcode`anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].source_account_id`anyOf 1	`string`مطلوب في العنصر الأب	`pattern: "^[0-9]{1,30}$"`
`retrieval.result.posts[].author`anyOf 1	`string`مطلوب في العنصر الأب	`minLength: 1` `maxLength: 50`
`retrieval.result.posts[].canonical_url`anyOf 1	`string`مطلوب في العنصر الأب	`format: "uri"` `maxLength: 2048`
`retrieval.result.posts[].text`anyOf 1	`string`مطلوب في العنصر الأب	`maxLength: 30000`
`retrieval.result.posts[].published_at`anyOf 1	`string \| null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].published_at`anyOf 1 / anyOf 1	`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)))$"`
`retrieval.result.posts[].published_at`anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].media_kind`anyOf 1	`string`مطلوب في العنصر الأب	`enum: ["text","image","video","carousel","unknown"]`
`retrieval.result.posts[].metrics`anyOf 1	`object`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.likes`anyOf 1	`integer \| null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.likes`anyOf 1 / anyOf 1	`integer`مطلوب في العنصر الأب	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.likes`anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.comments`anyOf 1	`integer \| null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.comments`anyOf 1 / anyOf 1	`integer`مطلوب في العنصر الأب	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.comments`anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.reactions`anyOf 1	`integer \| null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.reactions`anyOf 1 / anyOf 1	`integer`مطلوب في العنصر الأب	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.reactions`anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.shares`anyOf 1	`integer \| null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.shares`anyOf 1 / anyOf 1	`integer`مطلوب في العنصر الأب	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.shares`anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.views`anyOf 1	`integer \| null`مطلوب في العنصر الأب	—
`retrieval.result.posts[].metrics.views`anyOf 1 / anyOf 1	`integer`مطلوب في العنصر الأب	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.views`anyOf 1 / anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.result.coverage`anyOf 1	`object`مطلوب في العنصر الأب	—
`retrieval.result.coverage.complete`anyOf 1	`boolean`مطلوب في العنصر الأب	`const: false`
`retrieval.result.coverage.reasons`anyOf 1	`array`مطلوب في العنصر الأب	`maxItems: 20`
`retrieval.result.coverage.reasons[]`anyOf 1	`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"]`
`retrieval.result.coverage.omitted_rows`anyOf 1	`integer`مطلوب في العنصر الأب	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.coverage.next_cursor`anyOf 1	`null`مطلوب في العنصر الأب	—
`retrieval.result`anyOf 2	`null`مطلوب في العنصر الأب	—
`retrieval.evidence`	`array`مطلوب في العنصر الأب	`maxItems: 20`
`retrieval.evidence[]`	`object`اختياري / عنصر	—
`retrieval.evidence[].evidence_id`	`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)$"`
`retrieval.evidence[].revision`	`integer`مطلوب في العنصر الأب	`maximum: 9007199254740991` `exclusiveMinimum: 0`

مخطط JSON Schema الكامل

{
  "$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"
  ]
}

الأخطاء وإعادة المحاولة بأمان

افحص حالة HTTP والجسم. قد يحوي خطأ التحقق 400 ‏ZodError؛ تستخدم أخطاء المعالج error و message و code. احتفظ بـ request_id أو x-request-id للتشخيص دون اعتماد. أصلح أخطاء وصول 401/403 قبل المحاولة واتّبع Retry-After لـ 429. لكتابة غير مؤكدة أو 5xx، اقرأ الموجود أولاً. أعِد مفتاح منع التكرار حيث يُدعم فقط؛ تختلف المحاولة حسب العملية ولا تضمن التسليم مرة واحدة بالضبط.

دليل استكشاف الأخطاء وإصلاحها

أمثلة

تستخدم الأمثلة قيماً خيالية مفحوصة بالمخططات. استبدل المعرّفات بالمفوّض لك، والوسائط بأصول جاهزة، والتواريخ بوقت نشر مؤكد. افحص أهلية الحساب قبل الكتابة. لا تُرسل الصفحة طلبات API.

اضبط SOSOAPI_ACCESS_TOKEN على خادمك ببيانات اعتماد تقبلها العملية، وأبقِه خارج شيفرة المتصفح. لوكيل الذكاء الاصطناعي، استخدم sosoapi auth login للدخول بالمتصفح ودع CLI يحدّث بيانات اعتماده.

request.json

{
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "mutation_id": "40000000-0000-4000-8000-000000000005",
  "url": "https://www.instagram.com/fictional_example/"
}

cURL

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

// 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

# 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

مثال استجابة اصطناعية

{
  "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
      }
    }
  }
}

MCP: sosoapi_research_evidence_retrieve-social

جميع عمليات API المصادقة والأذونات

تفضيلات الخصوصية

الوظائف الضرورية

تشخيصات Landing وإعادة العرض مع إخفاء المحتوى

تحليلات الاستخدام الاختيارية

السماح أيضاً بتسجيل الجلسات لإعادة عرضها على هذا الموقع العام

قراءة مصدر بحث اجتماعي عام

نظرة عامة

المصادقة والأذونات

حقول الطلب

الاستجابة والاكتمال

الأخطاء وإعادة المحاولة بأمان

أمثلة

request.json

cURL

JavaScript

CLI

مثال استجابة اصطناعية

قراءة مصدر بحث اجتماعي عام

نظرة عامة

المصادقة والأذونات

حقول الطلب

الاستجابة والاكتمال

الأخطاء وإعادة المحاولة بأمان

أمثلة

request.json

cURL

JavaScript

CLI

مثال استجابة اصطناعية

أدوات وأدلة ذات صلة