Research and cited briefs

Read public social source retrieval status

Read the same social retrieval by mutation_id; untrusted source text may be expired or unavailable. Requires agent:research.

POST /research-api/evidence/social-status

Contract reviewed: 2026-11-03 · sha256:dadbfeb34d10743d

Read as Markdown Download public contract Download OpenAPI

Overview

Read the same social retrieval by mutation_id; untrusted source text may be expired or unavailable. Requires agent:research.

A successful HTTP response can mean that a request was accepted rather than completed. For background work, save the returned ID and check the same operation until it finishes. A scheduled or accepted post is published only when the platform confirms it; a client timeout does not establish the result.

Authentication and permissions

Accepted credential classes: user_session, delegated_oauth, personal_access_token
Delegated capability: agent:research
Minimum workspace role: viewer
Access scope: Resources this user is authorized to access
All-workspace consent required: No
Changes state: No
When the operation is complete: current authorized social receipt and evidence; removed or expired source content is redacted

A token can use only the rights held by its owner. Each request checks workspace membership, resource ownership, selected workspaces and granted capabilities. Core and full profiles change which tools are displayed; they do not grant access.

Request fields

Required means required inside its parent object and selected branch. A required child does not make an optional parent required. Rules and field names below are copied from the contract.

Request fields
Field / branch	Type / required	Constraints
`$`	`object`Required in parent	`additionalProperties: false`
`workspace_id`	`string`Required in parent	`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`Required in parent	`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)$"`

Complete 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)$"
    }
  },
  "required": [
    "workspace_id",
    "mutation_id"
  ],
  "additionalProperties": false
}

Response and completion

Success HTTP statuses: 200. When the operation is complete: current authorized social receipt and evidence; removed or expired source content is redacted.

Required means required inside its parent object and selected branch. A required child does not make an optional parent required. Rules and field names below are copied from the contract.

Response and completion
Field / branch	Type / required	Constraints
`$`	`object`Required in parent	—
`retrieval`	`object \| null`Required in parent	—
`retrieval`anyOf 1	`object`Required in parent	—
`retrieval.id`anyOf 1	`string`Required in parent	`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`anyOf 1	`string`Required in parent	`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`anyOf 1	`string`Required in parent	`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`anyOf 1	`string`Required in parent	`const: "public_social"`
`retrieval.state`anyOf 1	`string`Required in parent	`enum: ["pending","running","completed","cancelled","unconfirmed","expired"]`
`retrieval.created_at`anyOf 1	`string`Required in parent	`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 1	`string \| null`Required in parent	—
`retrieval.settled_at`anyOf 1 / anyOf 1	`string`Required in parent	`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 1 / anyOf 2	`null`Required in parent	—
`retrieval.valid_until`anyOf 1	`string`Required in parent	`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`anyOf 1	`object \| null`Required in parent	—
`retrieval.result`anyOf 1 / anyOf 1	`object`Required in parent	—
`retrieval.result.source`anyOf 1 / anyOf 1	`string`Required in parent	`enum: ["facebook_public_web","instagram_public_web","threads_public_web"]`
`retrieval.result.platform`anyOf 1 / anyOf 1	`string`Required in parent	`enum: ["facebook","instagram","threads"]`
`retrieval.result.canonical_url`anyOf 1 / anyOf 1	`string`Required in parent	`format: "uri"` `maxLength: 2048`
`retrieval.result.fetched_at`anyOf 1 / anyOf 1	`string`Required in parent	`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 / anyOf 1	`string`Required in parent	`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 / anyOf 1	`null`Required in parent	—
`retrieval.result.status`anyOf 1 / anyOf 1	`string`Required in parent	`enum: ["available","partial","unavailable"]`
`retrieval.result.profile`anyOf 1 / anyOf 1	`object \| null`Required in parent	—
`retrieval.result.profile`anyOf 1 / anyOf 1 / anyOf 1	`object`Required in parent	—
`retrieval.result.profile.source_account_id`anyOf 1 / anyOf 1 / anyOf 1	`string`Required in parent	`pattern: "^[0-9]{1,30}$"`
`retrieval.result.profile.id_namespace`anyOf 1 / anyOf 1 / anyOf 1	`string`Required in parent	`const: "public_web"`
`retrieval.result.profile.username`anyOf 1 / anyOf 1 / anyOf 1	`string`Required in parent	`minLength: 1` `maxLength: 50`
`retrieval.result.profile.name`anyOf 1 / anyOf 1 / anyOf 1	`string \| null`Required in parent	—
`retrieval.result.profile.name`anyOf 1 / anyOf 1 / anyOf 1 / anyOf 1	`string`Required in parent	`minLength: 1` `maxLength: 200`
`retrieval.result.profile.name`anyOf 1 / anyOf 1 / anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.profile.followers`anyOf 1 / anyOf 1 / anyOf 1	`integer \| null`Required in parent	—
`retrieval.result.profile.followers`anyOf 1 / anyOf 1 / anyOf 1 / anyOf 1	`integer`Required in parent	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.profile.followers`anyOf 1 / anyOf 1 / anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.profile`anyOf 1 / anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.posts`anyOf 1 / anyOf 1	`array`Required in parent	`maxItems: 20`
`retrieval.result.posts[]`anyOf 1 / anyOf 1	`object`Optional / item	—
`retrieval.result.posts[].source_post_id`anyOf 1 / anyOf 1	`string`Required in parent	`pattern: "^[0-9]{1,30}$"`
`retrieval.result.posts[].id_namespace`anyOf 1 / anyOf 1	`string`Required in parent	`const: "public_web"`
`retrieval.result.posts[].shortcode`anyOf 1 / anyOf 1	`string \| null`Required in parent	—
`retrieval.result.posts[].shortcode`anyOf 1 / anyOf 1 / anyOf 1	`string`Required in parent	`minLength: 1` `maxLength: 64`
`retrieval.result.posts[].shortcode`anyOf 1 / anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.posts[].source_account_id`anyOf 1 / anyOf 1	`string`Required in parent	`pattern: "^[0-9]{1,30}$"`
`retrieval.result.posts[].author`anyOf 1 / anyOf 1	`string`Required in parent	`minLength: 1` `maxLength: 50`
`retrieval.result.posts[].canonical_url`anyOf 1 / anyOf 1	`string`Required in parent	`format: "uri"` `maxLength: 2048`
`retrieval.result.posts[].text`anyOf 1 / anyOf 1	`string`Required in parent	`maxLength: 30000`
`retrieval.result.posts[].published_at`anyOf 1 / anyOf 1	`string \| null`Required in parent	—
`retrieval.result.posts[].published_at`anyOf 1 / anyOf 1 / anyOf 1	`string`Required in parent	`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 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.posts[].media_kind`anyOf 1 / anyOf 1	`string`Required in parent	`enum: ["text","image","video","carousel","unknown"]`
`retrieval.result.posts[].metrics`anyOf 1 / anyOf 1	`object`Required in parent	—
`retrieval.result.posts[].metrics.likes`anyOf 1 / anyOf 1	`integer \| null`Required in parent	—
`retrieval.result.posts[].metrics.likes`anyOf 1 / anyOf 1 / anyOf 1	`integer`Required in parent	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.likes`anyOf 1 / anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.posts[].metrics.comments`anyOf 1 / anyOf 1	`integer \| null`Required in parent	—
`retrieval.result.posts[].metrics.comments`anyOf 1 / anyOf 1 / anyOf 1	`integer`Required in parent	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.comments`anyOf 1 / anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.posts[].metrics.reactions`anyOf 1 / anyOf 1	`integer \| null`Required in parent	—
`retrieval.result.posts[].metrics.reactions`anyOf 1 / anyOf 1 / anyOf 1	`integer`Required in parent	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.reactions`anyOf 1 / anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.posts[].metrics.shares`anyOf 1 / anyOf 1	`integer \| null`Required in parent	—
`retrieval.result.posts[].metrics.shares`anyOf 1 / anyOf 1 / anyOf 1	`integer`Required in parent	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.shares`anyOf 1 / anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.posts[].metrics.views`anyOf 1 / anyOf 1	`integer \| null`Required in parent	—
`retrieval.result.posts[].metrics.views`anyOf 1 / anyOf 1 / anyOf 1	`integer`Required in parent	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.posts[].metrics.views`anyOf 1 / anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.result.coverage`anyOf 1 / anyOf 1	`object`Required in parent	—
`retrieval.result.coverage.complete`anyOf 1 / anyOf 1	`boolean`Required in parent	`const: false`
`retrieval.result.coverage.reasons`anyOf 1 / anyOf 1	`array`Required in parent	`maxItems: 20`
`retrieval.result.coverage.reasons[]`anyOf 1 / anyOf 1	`string`Optional / item	`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 / anyOf 1	`integer`Required in parent	`minimum: 0` `maximum: 9007199254740991`
`retrieval.result.coverage.next_cursor`anyOf 1 / anyOf 1	`null`Required in parent	—
`retrieval.result`anyOf 1 / anyOf 2	`null`Required in parent	—
`retrieval.evidence`anyOf 1	`array`Required in parent	`maxItems: 20`
`retrieval.evidence[]`anyOf 1	`object`Optional / item	—
`retrieval.evidence[].evidence_id`anyOf 1	`string`Required in parent	`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`anyOf 1	`integer`Required in parent	`maximum: 9007199254740991` `exclusiveMinimum: 0`
`retrieval`anyOf 2	`null`Required in parent	—

Complete JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "retrieval": {
      "anyOf": [
        {
          "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"
          ]
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "retrieval"
  ]
}

Errors and safe retries

Check the HTTP status and response body. A 400 validation error may contain a ZodError; handler errors use error, message and code fields. Keep request_id or x-request-id for diagnosis, without credentials. Fix 401/403 access errors before retrying, and follow Retry-After for 429. If a write is uncertain or returns 5xx, read the existing result first. Reuse an idempotency key only where supported; retry behaviour varies by operation and does not guarantee exactly-once delivery.

Troubleshooting guide

Examples

These examples use fictional values checked against the schemas. Replace the IDs with ones you are authorized to use, the media with ready assets and the dates with your confirmed publishing time. Check the account’s eligibility before submitting a write. This page sends no API requests.

Set SOSOAPI_ACCESS_TOKEN on your server to a credential accepted by this operation, and keep it out of browser code. For an AI Agent, use sosoapi auth login to sign in through the browser and let the CLI refresh its credentials.

request.json

{
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "mutation_id": "40000000-0000-4000-8000-000000000005"
}

cURL

curl --request POST \
  "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/research-api/evidence/social-status" \
  -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/social-status", {
  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"
})
});
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/social-status < request.json

Synthetic response example

{
  "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_social-status

All API operations Authentication and permissions

Privacy preferences

Necessary features

Landing diagnostics & masked replay

Optional usage analytics

Also allow session replay on this public website

Read public social source retrieval status

Overview

Authentication and permissions

Request fields

Response and completion

Errors and safe retries

Examples

request.json

cURL

JavaScript

CLI

Synthetic response example

Read public social source retrieval status

Overview

Authentication and permissions

Request fields

Response and completion

Errors and safe retries

Examples

request.json

cURL

JavaScript

CLI

Synthetic response example

Related tools and guides