api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "lookupStatus": {
          "description": "Whether the requested profile or page resolved for this request.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        },
        "page": {
          "description": "Pagination information for the current response.",
          "properties": {
            "hasMore": {
              "description": "Whether another page of reels can be requested.",
              "type": "boolean"
            },
            "nextCursor": {
              "description": "Cursor to pass as `cursor` in the next request when `hasMore` is true; otherwise null.",
              "nullable": true,
              "type": "string"
            }
          },
          "required": [
            "nextCursor",
            "hasMore"
          ],
          "type": "object"
        },
        "reels": {
          "description": "Reels returned for the requested profile or page. This array may be empty on the last page.",
          "items": {
            "description": "A single Facebook reel on a profile reels page.",
            "properties": {
              "author": {
                "description": "Author metadata when available.",
                "nullable": true,
                "properties": {
                  "imageUrl": {
                    "description": "Profile image URL for the author when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "isVerified": {
                    "description": "Whether Facebook marks the author as verified.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "name": {
                    "description": "Display name for the reel author when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "platformUserId": {
                    "description": "Facebook id for the reel author when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "url": {
                    "description": "Public Facebook URL for the author when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "platformUserId",
                  "name",
                  "isVerified",
                  "url",
                  "imageUrl"
                ],
                "type": "object"
              },
              "createdAt": {
                "description": "ISO-8601 timestamp for when the reel was created.",
                "nullable": true,
                "type": "string"
              },
              "description": {
                "description": "Caption or description text when available.",
                "nullable": true,
                "type": "string"
              },
              "durationMs": {
                "description": "Play duration in milliseconds when available.",
                "minimum": 0,
                "nullable": true,
                "type": "integer"
              },
              "hostedMedia": {
                "description": "Present only when `hostMedia=true`. Hosted copies and/or per-asset failures for this reel.",
                "items": {
                  "description": "SocialFetch-hosted original media asset or per-asset failure.",
                  "properties": {
                    "bytes": {
                      "description": "Stored size in bytes when status is stored.",
                      "minimum": 0,
                      "type": "integer"
                    },
                    "entityId": {
                      "description": "Opaque parent entity id for this asset (post, reel, photo, or video id).",
                      "minLength": 1,
                      "type": "string"
                    },
                    "errorCode": {
                      "description": "Typed failure code when status is failed.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "errorMessage": {
                      "description": "Short customer-safe failure message when status is failed.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "expiresAt": {
                      "description": "ISO-8601 timestamp when the returned delivery URL stops working.",
                      "format": "date-time",
                      "type": "string"
                    },
                    "height": {
                      "description": "Pixel height when known.",
                      "exclusiveMinimum": true,
                      "minimum": 0,
                      "nullable": true,
                      "type": "integer"
                    },
                    "mime": {
                      "description": "MIME type of the stored bytes when status is stored.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "originalUrl": {
                      "description": "Source-platform CDN URL that was requested for hosting. Still transient; prefer `url` when status is stored.",
                      "format": "uri",
                      "type": "string"
                    },
                    "postId": {
                      "description": "Legacy Instagram media id alias for `entityId`. Prefer `entityId`.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "retainedUntil": {
                      "description": "ISO-8601 timestamp when the stored object is deleted from SocialFetch storage (90-day tier).",
                      "format": "date-time",
                      "type": "string"
                    },
                    "role": {
                      "description": "Which source field this asset was derived from.",
                      "enum": [
                        "display",
                        "thumbnail",
                        "video"
                      ],
                      "type": "string"
                    },
                    "status": {
                      "description": "Whether SocialFetch stored a durable copy of this asset.",
                      "enum": [
                        "stored",
                        "failed"
                      ],
                      "type": "string"
                    },
                    "type": {
                      "description": "Normalized media kind.",
                      "enum": [
                        "image",
                        "video"
                      ],
                      "type": "string"
                    },
                    "url": {
                      "description": "Time-limited SocialFetch delivery URL when status is stored. Re-request hostMedia (or a future refresh route) before this expires if you still need access; object retention may outlive the delivery URL.",
                      "format": "uri",
                      "type": "string"
                    },
                    "width": {
                      "description": "Pixel width when known.",
                      "exclusiveMinimum": true,
                      "minimum": 0,
                      "nullable": true,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "status",
                    "type"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "id": {
                "description": "Stable reel identifier from Facebook.",
                "minLength": 1,
                "type": "string"
              },
              "music": {
                "description": "Music metadata when available.",
                "nullable": true,
                "properties": {
                  "title": {
                    "description": "Music track title when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "title"
                ],
                "type": "object"
              },
              "postId": {
                "description": "Underlying Facebook post id when available.",
                "nullable": true,
                "type": "string"
              },
              "thumbnailUrl": {
                "description": "Source-platform CDN URL for the thumbnail when available. It can expire or be rejected outside the original retrieval context; it is not a SocialFetch-hosted asset. Null when no syntactically usable URL is available. For durable hosted copies on this list route, pass `hostMedia=true`.",
                "nullable": true,
                "type": "string"
              },
              "url": {
                "description": "Public Facebook URL for this reel.",
                "minLength": 1,
                "type": "string"
              },
              "videoId": {
                "description": "Underlying Facebook video id when available.",
                "nullable": true,
                "type": "string"
              },
              "videoUrl": {
                "description": "Source-platform CDN URL for the video when available. It can expire or be rejected outside the original retrieval context; it is not a SocialFetch-hosted asset. Null when no syntactically usable URL is available. For durable hosted copies on this list route, pass `hostMedia=true`.",
                "nullable": true,
                "type": "string"
              },
              "viewCount": {
                "description": "View count when available.",
                "minimum": 0,
                "nullable": true,
                "type": "integer"
              }
            },
            "required": [
              "id",
              "postId",
              "videoId",
              "url",
              "description",
              "createdAt",
              "viewCount",
              "thumbnailUrl",
              "videoUrl",
              "durationMs",
              "music",
              "author"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "lookupStatus",
        "reels",
        "page"
      ],
      "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"
}