api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "author": {
          "description": "Author when found.",
          "nullable": true,
          "properties": {
            "avatarUrl": {
              "description": "Avatar image URL.",
              "nullable": true,
              "type": "string"
            },
            "displayName": {
              "description": "Display name.",
              "nullable": true,
              "type": "string"
            },
            "handle": {
              "description": "Threads username without a leading @.",
              "minLength": 1,
              "type": "string"
            },
            "platform": {
              "description": "Social platform for this author.",
              "enum": [
                "threads"
              ],
              "type": "string"
            },
            "platformUserId": {
              "description": "Numeric profile id.",
              "type": "string"
            },
            "privateAccount": {
              "description": "Whether the account is private.",
              "type": "boolean"
            },
            "verified": {
              "description": "Whether the profile is verified.",
              "type": "boolean"
            }
          },
          "required": [
            "platform",
            "handle",
            "verified"
          ],
          "type": "object"
        },
        "lookupStatus": {
          "description": "Whether the post was found.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        },
        "media": {
          "description": "Primary media payload for the post.",
          "nullable": true,
          "properties": {
            "accessibilityCaption": {
              "description": "Accessibility description when available.",
              "nullable": true,
              "type": "string"
            },
            "dimensions": {
              "description": "Original dimensions when available.",
              "properties": {
                "height": {
                  "minimum": 0,
                  "type": "integer"
                },
                "width": {
                  "minimum": 0,
                  "type": "integer"
                }
              },
              "required": [
                "width",
                "height"
              ],
              "type": "object"
            },
            "images": {
              "description": "Image renditions.",
              "items": {
                "description": "One image or video rendition.",
                "properties": {
                  "height": {
                    "description": "Height in pixels when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "url": {
                    "description": "Media URL.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "width": {
                    "description": "Width in pixels when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "required": [
                  "url"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "mediaType": {
              "description": "Normalized media kind.",
              "enum": [
                "text",
                "image",
                "video",
                "carousel",
                "unknown"
              ],
              "type": "string"
            },
            "videos": {
              "description": "Video renditions.",
              "items": {
                "description": "One image or video rendition.",
                "properties": {
                  "height": {
                    "description": "Height in pixels when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "url": {
                    "description": "Media URL.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "width": {
                    "description": "Width in pixels when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "required": [
                  "url"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "mediaType",
            "images",
            "videos"
          ],
          "type": "object"
        },
        "metrics": {
          "description": "Engagement metrics for a Threads post.",
          "nullable": true,
          "properties": {
            "likes": {
              "description": "Like count when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "quotes": {
              "description": "Quote count when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "replies": {
              "description": "Direct reply count when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "reposts": {
              "description": "Repost count when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "reshares": {
              "description": "Reshare count when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "views": {
              "description": "View count when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            }
          },
          "type": "object"
        },
        "post": {
          "description": "Primary post when found.",
          "nullable": true,
          "properties": {
            "caption": {
              "description": "Caption text.",
              "nullable": true,
              "type": "string"
            },
            "createdAt": {
              "description": "When the post was published (ISO-8601).",
              "format": "date-time",
              "type": "string"
            },
            "id": {
              "description": "Post id.",
              "minLength": 1,
              "type": "string"
            },
            "isReply": {
              "description": "Whether this post is a reply.",
              "type": "boolean"
            },
            "replyControl": {
              "description": "Reply audience setting when available.",
              "nullable": true,
              "type": "string"
            },
            "shortcode": {
              "description": "Public shortcode for the post.",
              "minLength": 1,
              "type": "string"
            },
            "unavailableReason": {
              "description": "Reason when content is unavailable.",
              "nullable": true,
              "type": "string"
            },
            "url": {
              "description": "Canonical public Threads URL.",
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "id",
            "shortcode",
            "url",
            "caption",
            "createdAt"
          ],
          "type": "object"
        },
        "relatedPosts": {
          "description": "Related posts when available.",
          "items": {
            "description": "A related Threads post or reply.",
            "properties": {
              "author": {
                "description": "Author when known.",
                "nullable": true,
                "properties": {
                  "avatarUrl": {
                    "description": "Avatar image URL.",
                    "nullable": true,
                    "type": "string"
                  },
                  "displayName": {
                    "description": "Display name.",
                    "nullable": true,
                    "type": "string"
                  },
                  "handle": {
                    "description": "Threads username without a leading @.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "platform": {
                    "description": "Social platform for this author.",
                    "enum": [
                      "threads"
                    ],
                    "type": "string"
                  },
                  "platformUserId": {
                    "description": "Numeric profile id.",
                    "type": "string"
                  },
                  "privateAccount": {
                    "description": "Whether the account is private.",
                    "type": "boolean"
                  },
                  "verified": {
                    "description": "Whether the profile is verified.",
                    "type": "boolean"
                  }
                },
                "required": [
                  "platform",
                  "handle",
                  "verified"
                ],
                "type": "object"
              },
              "caption": {
                "description": "Caption text.",
                "nullable": true,
                "type": "string"
              },
              "createdAt": {
                "description": "When published (ISO-8601).",
                "format": "date-time",
                "type": "string"
              },
              "id": {
                "description": "Post id.",
                "minLength": 1,
                "type": "string"
              },
              "metrics": {
                "description": "Engagement metrics for a Threads post.",
                "nullable": true,
                "properties": {
                  "likes": {
                    "description": "Like count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "quotes": {
                    "description": "Quote count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "replies": {
                    "description": "Direct reply count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "reposts": {
                    "description": "Repost count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "reshares": {
                    "description": "Reshare count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "views": {
                    "description": "View count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "shortcode": {
                "description": "Public shortcode.",
                "minLength": 1,
                "type": "string"
              },
              "url": {
                "description": "Canonical public Threads URL.",
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "id",
              "shortcode",
              "url",
              "caption",
              "createdAt",
              "author",
              "metrics"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "replies": {
          "description": "Top-level replies when available.",
          "items": {
            "description": "A related Threads post or reply.",
            "properties": {
              "author": {
                "description": "Author when known.",
                "nullable": true,
                "properties": {
                  "avatarUrl": {
                    "description": "Avatar image URL.",
                    "nullable": true,
                    "type": "string"
                  },
                  "displayName": {
                    "description": "Display name.",
                    "nullable": true,
                    "type": "string"
                  },
                  "handle": {
                    "description": "Threads username without a leading @.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "platform": {
                    "description": "Social platform for this author.",
                    "enum": [
                      "threads"
                    ],
                    "type": "string"
                  },
                  "platformUserId": {
                    "description": "Numeric profile id.",
                    "type": "string"
                  },
                  "privateAccount": {
                    "description": "Whether the account is private.",
                    "type": "boolean"
                  },
                  "verified": {
                    "description": "Whether the profile is verified.",
                    "type": "boolean"
                  }
                },
                "required": [
                  "platform",
                  "handle",
                  "verified"
                ],
                "type": "object"
              },
              "caption": {
                "description": "Caption text.",
                "nullable": true,
                "type": "string"
              },
              "createdAt": {
                "description": "When published (ISO-8601).",
                "format": "date-time",
                "type": "string"
              },
              "id": {
                "description": "Post id.",
                "minLength": 1,
                "type": "string"
              },
              "metrics": {
                "description": "Engagement metrics for a Threads post.",
                "nullable": true,
                "properties": {
                  "likes": {
                    "description": "Like count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "quotes": {
                    "description": "Quote count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "replies": {
                    "description": "Direct reply count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "reposts": {
                    "description": "Repost count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "reshares": {
                    "description": "Reshare count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "views": {
                    "description": "View count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "shortcode": {
                "description": "Public shortcode.",
                "minLength": 1,
                "type": "string"
              },
              "url": {
                "description": "Canonical public Threads URL.",
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "id",
              "shortcode",
              "url",
              "caption",
              "createdAt",
              "author",
              "metrics"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "lookupStatus",
        "post",
        "author",
        "metrics",
        "media",
        "replies",
        "relatedPosts"
      ],
      "type": "object"
    },
    "meta": {
      "description": "Metadata describing the request and billing outcome.",
      "properties": {
        "cached": {
          "description": "True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.",
          "type": "boolean"
        },
        "creditsCharged": {
          "description": "Credits charged for this request.",
          "minimum": 0,
          "type": "integer"
        },
        "requestId": {
          "description": "Unique request identifier for tracing this API call.",
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Public API version that served the response.",
          "enum": [
            "v1"
          ],
          "type": "string"
        }
      },
      "required": [
        "requestId",
        "creditsCharged",
        "version"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "type": "object"
}