Skip to main content
Glama
Sign In

ReachSocial - One API for social media data.

by dev.reachsocial
OverviewDiscussionsAdmin

Retrieve ReachSocial request

get_reachsocial_request
Read-onlyIdempotent

Retrieve an OAuth request's payment state or stored social-data result.

Use after a social-data tool returns request_id, especially after browser
payment or a lost response. Requires the same OAuth wallet and client that
created it; B2B API keys cannot retrieve OAuth requests. Missing, expired
retention, or inaccessible IDs return an error. This only reads stored work:
no provider call or payment. For awaiting_approval/reconciliation_required,
retrieve this same request again; never create a new payment to recover it.

Input Schema

NameRequiredDescriptionDefault
request_idYesThe exact request_id returned by a social-data tool under OAuth. Preserve this ID across browser payment and retries.

Output Schema

NameRequiredDescriptionDefault
dataNoDirect B2B normalized profile, item, or items; feeds may include next_cursor and has_more.
metaNoDirect B2B schema/normalization versions, response shape, and latency.
cachedNoWhether a direct B2B response reused cached normalized data.
resultNoStored execution response after OAuth payment; contains normalized data or a terminal failure.
statusYesB2B success or the current OAuth payment/execution state.
messageNoAction or recovery guidance for the current request state.
serviceYesCatalog service ID, such as instagram.profile.
request_idYesStored request identifier; preserve it for recovery.
payment_urlNoOwner browser link for USDC payment approval; present when payment is required.
price_centsNoOAuth request price in USD cents.
transactionNoSettled payment transaction identifier, when available.
payment_statusNoStored settlement state; uncertainty requires retrieval, never a new payment.
payment_endpointNoOwner-only acceptance endpoint, present only during an explicitly enabled validation run.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • addedInput schema / properties / request_id / description
      Added value: +"The exact request_id returned by a social-data tool under OAuth. Preserve this ID across browser payment and retries."
    • addedInput schema / properties / request_id / maxLength
      Added value: +64
    • addedInput schema / properties / request_id / minLength
      Added value: +64
    • addedInput schema / properties / request_id / pattern
      Added value: +"^[0-9a-f]{64}$"
    • changedInput schema / title
      Previous value: -"retrieve_requestArguments"New value: +"get_reachsocial_requestArguments"
    • addedOutput schema / description
      Added value: +"A B2B execution result or an OAuth request awaiting browser payment."
    • addedOutput schema / properties
      Added value: +{
+  "cached": {
+    "description": "Whether a direct B2B response reused cached normalized data.",
+    "title": "Cached",
+    "type": "boolean"
+  },
+  "data": {
+    "additionalProperties": true,
+    "description": "Direct B2B normalized profile, item, or items; feeds may include next_cursor and has_more.",
+    "title": "Data",
+    "type": "object"
+  },
+  "message": {
+    "description": "Action or recovery guidance for the current request state.",
+    "title": "Message",
+    "type": "string"
+  },
+  "meta": {
+    "additionalProperties": true,
+    "description": "Direct B2B schema/normalization versions, response shape, and latency.",
+    "title": "Meta",
+    "type": "object"
+  },
+  "payment_endpoint": {
+    "description": "Owner-only acceptance endpoint, present only during an explicitly enabled validation run.",
+    "title": "Payment Endpoint",
+    "type": "string"
+  },
+  "payment_status": {
+    "description": "Stored settlement state; uncertainty requires retrieval, never a new payment.",
+    "title": "Payment Status",
+    "type": "string"
+  },
+  "payment_url": {
+    "description": "Owner browser link for USDC payment approval; present when payment is required.",
+    "title": "Payment Url",
+    "type": "string"
+  },
+  "price_cents": {
+    "description": "OAuth request price in USD cents.",
+    "title": "Price Cents",
+    "type": "integer"
+  },
+  "request_id": {
+    "description": "Stored request identifier; preserve it for recovery.",
+    "title": "Request Id",
+    "type": "string"
+  },
+  "result": {
+    "additionalProperties": true,
+    "description": "Stored execution response after OAuth payment; contains normalized data or a terminal failure.",
+    "title": "Result",
+    "type": "object"
+  },
+  "service": {
+    "description": "Catalog service ID, such as instagram.profile.",
+    "title": "Service",
+    "type": "string"
+  },
+  "status": {
+    "description": "B2B success or the current OAuth payment/execution state.",
+    "enum": [
+      "success",
+      "payment_required",
+      "awaiting_approval",
+      "reconciliation_required",
+      "succeeded",
+      "failed",
+      "expired"
+    ],
+    "title": "Status",
+    "type": "string"
+  },
+  "transaction": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "description": "Settled payment transaction identifier, when available.",
+    "title": "Transaction"
+  }
+}
    • addedOutput schema / required
      Added value: +[
+  "request_id",
+  "service",
+  "status"
+]
    • changedOutput schema / title
      Previous value: -"retrieve_requestDictOutput"New value: +"MCPServiceResult"
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses auth requirements (same OAuth wallet and client, no B2B API keys), error behavior for missing/expired/inaccessible IDs, and the important guarantee that this only reads stored work with no provider call or payment. It also gives operational recovery guidance for specific states, which is valuable behavioral context an agent would not get from annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by usage context, auth constraints, and recovery rules. Every sentence adds actionable information, and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that annotations cover safety, the schema fully documents the only parameter, and an output schema exists, the description is complete enough for correct invocation. It covers purpose, prerequisites, failure modes, and the critical recovery path without redundantly explaining return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the single request_id parameter is already fully documented with pattern, min/max length, and preservation guidance. The description does not add parameter syntax or format details beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: retrieve an OAuth request's payment state or stored social-data result. It distinguishes itself from the social-data sibling tools by clarifying that this only reads stored work and does not make a provider call or payment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use the tool: after a social-data tool returns a request_id, especially after browser payment or a lost response. It also gives when-not and recovery guidance, including that B2B API keys cannot retrieve OAuth requests and that awaiting_approval/reconciliation_required states should be retried on the same request rather than creating a new payment.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ReachSocial - One API for social media data. toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources