api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "coauthors": {
          "items": {
            "properties": {
              "avatarUrl": {
                "nullable": true,
                "type": "string"
              },
              "handle": {
                "minLength": 1,
                "type": "string"
              },
              "platformUserId": {
                "type": "string"
              },
              "verified": {
                "type": "boolean"
              }
            },
            "required": [
              "handle"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "downloads": {
          "description": "Provider-hosted media URLs when `downloadMedia` was true and media assets are available. Source Instagram CDN fields on `media` remain transient.",
          "items": {
            "description": "A downloaded media file.",
            "properties": {
              "cdnUrl": {
                "description": "Hosted URL when download succeeded (a durable CDN link). This is not SocialFetch-owned object storage; treat lifetime as externally defined.",
                "type": "string"
              },
              "originalUrl": {
                "description": "Original Instagram CDN URL.",
                "type": "string"
              },
              "postId": {
                "description": "Post or media id when present.",
                "type": "string"
              },
              "type": {
                "description": "Asset type.",
                "enum": [
                  "image",
                  "video"
                ],
                "type": "string"
              }
            },
            "required": [
              "originalUrl",
              "cdnUrl",
              "type"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "lookupStatus": {
          "description": "Whether the post or reel was resolved. Restricted covers age-gated or otherwise non-scrapable content.",
          "enum": [
            "found",
            "not_found",
            "restricted"
          ],
          "type": "string"
        },
        "media": {
          "description": "Primary media payload for the post.",
          "nullable": true,
          "properties": {
            "carouselChildren": {
              "description": "Sidecar children when this is a carousel.",
              "items": {
                "description": "One child item in a carousel (sidecar) post.",
                "properties": {
                  "displayUrl": {
                    "type": "string"
                  },
                  "id": {
                    "type": "string"
                  },
                  "isVideo": {
                    "type": "boolean"
                  },
                  "shortcode": {
                    "type": "string"
                  },
                  "videoUrl": {
                    "nullable": true,
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "type": "array"
            },
            "dimensions": {
              "description": "Dimensions for a media item.",
              "properties": {
                "height": {
                  "description": "Media height in pixels.",
                  "minimum": 0,
                  "type": "integer"
                },
                "width": {
                  "description": "Media width in pixels.",
                  "minimum": 0,
                  "type": "integer"
                }
              },
              "required": [
                "width",
                "height"
              ],
              "type": "object"
            },
            "displayUrl": {
              "nullable": true,
              "type": "string"
            },
            "mediaType": {
              "description": "Normalized media type.",
              "enum": [
                "image",
                "video",
                "sidecar",
                "unknown"
              ],
              "type": "string"
            },
            "productType": {
              "description": "Product type when present.",
              "nullable": true,
              "type": "string"
            },
            "thumbnailUrl": {
              "nullable": true,
              "type": "string"
            },
            "videoDurationSec": {
              "minimum": 0,
              "nullable": true,
              "type": "number"
            },
            "videoUrl": {
              "nullable": true,
              "type": "string"
            }
          },
          "required": [
            "mediaType"
          ],
          "type": "object"
        },
        "metrics": {
          "description": "Engagement metrics for the media.",
          "nullable": true,
          "properties": {
            "comments": {
              "description": "Comment count when Instagram exposes it.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "likes": {
              "description": "Like count when Instagram exposes it.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "playCount": {
              "description": "Play or view count for video/reel content when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            }
          },
          "type": "object"
        },
        "owner": {
          "description": "Author when found.",
          "nullable": true,
          "properties": {
            "avatarUrl": {
              "description": "Profile picture URL.",
              "nullable": true,
              "type": "string"
            },
            "fullName": {
              "description": "Display name when available.",
              "nullable": true,
              "type": "string"
            },
            "handle": {
              "description": "Instagram username without a leading @.",
              "minLength": 1,
              "type": "string"
            },
            "platformUserId": {
              "description": "Instagram numeric user id.",
              "type": "string"
            },
            "privateAccount": {
              "description": "Whether the account is private.",
              "type": "boolean"
            },
            "verified": {
              "description": "Whether the account is verified.",
              "type": "boolean"
            }
          },
          "required": [
            "handle",
            "verified"
          ],
          "type": "object"
        },
        "post": {
          "description": "Post details when found.",
          "nullable": true,
          "properties": {
            "accessibilityCaption": {
              "nullable": true,
              "type": "string"
            },
            "caption": {
              "description": "Caption text.",
              "nullable": true,
              "type": "string"
            },
            "createdAt": {
              "description": "When the media was taken or posted (ISO-8601).",
              "format": "date-time",
              "type": "string"
            },
            "id": {
              "description": "Instagram media id.",
              "minLength": 1,
              "type": "string"
            },
            "isAd": {
              "type": "boolean"
            },
            "isAffiliate": {
              "type": "boolean"
            },
            "isPaidPartnership": {
              "type": "boolean"
            },
            "shortcode": {
              "description": "Public shortcode.",
              "minLength": 1,
              "type": "string"
            },
            "url": {
              "description": "Canonical public Instagram URL for this media.",
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "id",
            "shortcode",
            "url",
            "caption",
            "createdAt"
          ],
          "type": "object"
        },
        "taggedUsers": {
          "items": {
            "description": "A user tagged in the media.",
            "properties": {
              "handle": {
                "description": "Tagged username.",
                "minLength": 1,
                "type": "string"
              },
              "platformUserId": {
                "type": "string"
              }
            },
            "required": [
              "handle"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "lookupStatus",
        "post",
        "owner",
        "metrics",
        "media",
        "downloads"
      ],
      "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"
}