api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "hashtag": {
          "description": "Hashtag evaluated for this response, without a leading #.",
          "type": "string"
        },
        "mediaType": {
          "description": "Content filter applied for this response.",
          "enum": [
            "all",
            "reels"
          ],
          "type": "string"
        },
        "page": {
          "description": "Pagination state for the current response.",
          "properties": {
            "hasMore": {
              "description": "Whether another page of results is available.",
              "type": "boolean"
            },
            "nextCursor": {
              "description": "Cursor to pass in the next request when another page exists.",
              "nullable": true,
              "type": "string"
            }
          },
          "required": [
            "nextCursor",
            "hasMore"
          ],
          "type": "object"
        },
        "posts": {
          "description": "Instagram posts matching the hashtag for the requested page. Empty when no posts match.",
          "items": {
            "description": "A single Instagram post in a hashtag search results page.",
            "properties": {
              "accessibilityCaption": {
                "description": "Accessibility caption when Instagram provides one.",
                "nullable": true,
                "type": "string"
              },
              "audio": {
                "description": "Audio attribution when Instagram exposes it.",
                "nullable": true,
                "properties": {
                  "artistName": {
                    "description": "Attributed artist name when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "audioId": {
                    "description": "Audio track id when Instagram provides one.",
                    "nullable": true,
                    "type": "string"
                  },
                  "shouldMuteAudio": {
                    "description": "Whether Instagram indicates the audio should be muted.",
                    "type": "boolean"
                  },
                  "shouldMuteAudioReason": {
                    "description": "Reason for muting audio when Instagram provides one.",
                    "nullable": true,
                    "type": "string"
                  },
                  "songName": {
                    "description": "Attributed song or audio title when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "usesOriginalAudio": {
                    "description": "Whether the post uses original audio.",
                    "type": "boolean"
                  }
                },
                "type": "object"
              },
              "caption": {
                "description": "Caption text when Instagram provides one.",
                "nullable": true,
                "type": "string"
              },
              "displayUrl": {
                "description": "Primary display image URL when available.",
                "type": "string"
              },
              "hasAudio": {
                "description": "Whether the post includes audio.",
                "type": "boolean"
              },
              "id": {
                "description": "Instagram media id for this post.",
                "minLength": 1,
                "type": "string"
              },
              "isAd": {
                "description": "Whether Instagram marks the post as an ad.",
                "type": "boolean"
              },
              "isAffiliate": {
                "description": "Whether Instagram marks the post as affiliate content.",
                "type": "boolean"
              },
              "isPaidPartnership": {
                "description": "Whether Instagram marks the post as a paid partnership.",
                "type": "boolean"
              },
              "isVideo": {
                "description": "Whether this media item is a video or Reel.",
                "type": "boolean"
              },
              "location": {
                "description": "Tagged location when Instagram exposes it.",
                "nullable": true,
                "properties": {
                  "addressJson": {
                    "description": "Serialized address metadata when Instagram provides it.",
                    "nullable": true,
                    "type": "string"
                  },
                  "id": {
                    "description": "Location id when Instagram provides one.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Location name when Instagram provides one.",
                    "nullable": true,
                    "type": "string"
                  },
                  "slug": {
                    "description": "Location slug when Instagram provides one.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "metrics": {
                "description": "Engagement metrics when Instagram exposes them.",
                "properties": {
                  "comments": {
                    "description": "Comment count when Instagram exposes it.",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "likes": {
                    "description": "Like count when Instagram exposes it.",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "plays": {
                    "description": "Play count when Instagram exposes it.",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "views": {
                    "description": "View count when Instagram exposes it.",
                    "minimum": 0,
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "owner": {
                "description": "Post owner metadata when Instagram exposes it.",
                "properties": {
                  "avatarUrl": {
                    "description": "Profile image URL for the post owner when present.",
                    "type": "string"
                  },
                  "displayName": {
                    "description": "Display name for the post owner when present.",
                    "type": "string"
                  },
                  "followerCount": {
                    "description": "Follower count when Instagram exposes it on the owner.",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "handle": {
                    "description": "Instagram username for the post owner when present.",
                    "type": "string"
                  },
                  "platformUserId": {
                    "description": "Instagram numeric user id for the post owner when present.",
                    "type": "string"
                  },
                  "postCount": {
                    "description": "Post count when Instagram exposes it on the owner.",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "privateAccount": {
                    "description": "Whether the post owner account is private.",
                    "type": "boolean"
                  },
                  "verified": {
                    "description": "Whether Instagram marks the post owner as verified.",
                    "type": "boolean"
                  }
                },
                "type": "object"
              },
              "shortcode": {
                "description": "Public shortcode used in the Instagram post URL.",
                "minLength": 1,
                "type": "string"
              },
              "takenAt": {
                "description": "When the post was taken or posted (Unix epoch seconds).",
                "type": "integer"
              },
              "thumbnailUrl": {
                "description": "Thumbnail or cover image URL when available.",
                "type": "string"
              },
              "url": {
                "description": "Canonical public Instagram URL for this post.",
                "minLength": 1,
                "type": "string"
              },
              "videoDurationSec": {
                "description": "Video duration in seconds when available.",
                "minimum": 0,
                "type": "number"
              },
              "videoUrl": {
                "description": "Direct video URL when a playable URL is available.",
                "type": "string"
              }
            },
            "required": [
              "id",
              "shortcode",
              "url",
              "caption",
              "takenAt",
              "isVideo"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "hashtag",
        "mediaType",
        "posts",
        "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"
}