{
  "openapi": "3.1.0",
  "info": {
    "title": "Fluxcrawl API",
    "version": "0.1.0",
    "description": "One stable API for live public and social data from TikTok, Instagram, and X. See [Introduction](/docs) for how the provider fallback chain works."
  },
  "servers": [
    {
      "url": "https://api.fluxcrawl.dev",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "TikTok",
      "description": "Backed by multiple upstream providers with automatic fallback. See [TikTok](/docs/tiktok) for endpoint-specific caveats."
    },
    {
      "name": "X",
      "description": "Backed by multiple upstream providers with automatic fallback. See [X](/docs/x) for endpoint-specific caveats. Read-only for now. Actions that post, follow, or message on your behalf aren't exposed."
    },
    {
      "name": "Instagram",
      "description": "Backed by an upstream data provider. See [Instagram](/docs/instagram) for endpoint-specific caveats."
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Required on every request. Keys are issued manually during early access, see [Authentication](/docs/authentication)."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "INVALID_API_KEY",
                  "INVALID_REQUEST",
                  "RESOURCE_NOT_FOUND",
                  "RATE_LIMITED",
                  "PROVIDER_UNAVAILABLE",
                  "INSUFFICIENT_CREDITS"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "credits_used": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "TikTokProfile": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "example": "tiktok"
          },
          "display_name": {
            "type": "string",
            "example": "TikTok"
          },
          "followers": {
            "type": "integer",
            "example": 95800000
          },
          "verified": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "TikTokPost": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "7680721699171601694"
          },
          "text": {
            "type": "string",
            "example": "this summer was all about the classic hits. here's to the ones that never got away 💿 #SongsofTheSummer2026"
          },
          "likes": {
            "type": "integer",
            "example": 14200
          },
          "comments": {
            "type": "integer",
            "example": 2458
          }
        }
      },
      "TikTokComment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "7680727229790126861"
          },
          "text": {
            "type": "string",
            "example": "yoo tiktok has tiktok"
          },
          "likes": {
            "type": "integer",
            "example": 665
          }
        }
      },
      "XProfile": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "example": "elonmusk"
          },
          "display_name": {
            "type": "string",
            "example": "Elon Musk"
          },
          "followers": {
            "type": "integer",
            "example": 241671501
          },
          "verified": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "XPost": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "2101767007406641574"
          },
          "text": {
            "type": "string",
            "example": "Cybertruck as Heavy Cav"
          },
          "likes": {
            "type": "integer",
            "example": 6648
          },
          "comments": {
            "type": "integer",
            "example": 875
          }
        }
      },
      "XComment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "2101808189197230387"
          },
          "text": {
            "type": "string",
            "example": "@elonmusk Fun Fact: The heaviest-duty Cybertruck variants can tow up to 11,000 pounds. \n\nHeavy cavalry checks out."
          },
          "likes": {
            "type": "integer",
            "example": 0
          }
        }
      },
      "InstagramProfile": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "example": "instagram"
          },
          "display_name": {
            "type": "string",
            "example": "Instagram"
          },
          "followers": {
            "type": "integer",
            "example": 686706771
          },
          "verified": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "InstagramPost": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "3989102446432402227"
          },
          "text": {
            "type": "string",
            "example": "the smile says it all 🥹\n\n#InTheMoment\n\nVideo by @wurzeltheween \n\nMusic by Louis Prima"
          },
          "likes": {
            "type": "integer",
            "example": 860541
          },
          "comments": {
            "type": "integer",
            "example": 10166
          }
        }
      },
      "InstagramComment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "17995953989821978"
          },
          "text": {
            "type": "string",
            "example": "Sooo sweet😊❤️❤️❤️❤️🍀"
          },
          "likes": {
            "type": "integer",
            "example": 16
          }
        }
      },
      "Community": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "1493446837214187523"
          },
          "name": {
            "type": "string",
            "example": "Build in Public"
          },
          "description": {
            "type": "string",
            "example": "Share what you're working on. Get feedback. Help each other move forward. – Sponsored by bolt.new ⚡"
          },
          "member_count": {
            "type": "integer",
            "example": 267427
          },
          "posts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/XPost"
            }
          }
        }
      },
      "Highlight": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "highlight:18029499352961095"
          },
          "title": {
            "type": "string",
            "example": "what's new"
          },
          "media_count": {
            "type": "integer",
            "example": 47
          }
        }
      },
      "Story": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "3991196691508326522"
          },
          "posted_at": {
            "type": "string",
            "example": "2026-09-21T16:22:20.000Z"
          },
          "expires_at": {
            "type": "string",
            "example": "2026-09-22T16:22:20.000Z"
          }
        }
      },
      "ProfileAbout": {
        "type": "object",
        "properties": {
          "joined_date": {
            "type": "string",
            "example": "February 2012"
          },
          "country": {
            "type": "string",
            "example": "United States"
          },
          "former_usernames": {
            "type": "string",
            "example": ""
          }
        }
      },
      "Location": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "233608000157522"
          },
          "name": {
            "type": "string",
            "example": "New York, N Y"
          },
          "posts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InstagramPost"
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "`INVALID_API_KEY`: missing, malformed, or revoked `X-API-Key`. See [Authentication](/docs/authentication).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "BadRequest": {
        "description": "`INVALID_REQUEST`: a required parameter is missing, or the endpoint name doesn't exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "`RESOURCE_NOT_FOUND`: the upstream platform confirmed the thing you asked for doesn't exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "`RATE_LIMITED`: the provider serving this request is rate-limiting you right now.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ProviderUnavailable": {
        "description": "`PROVIDER_UNAVAILABLE`: every provider in the fallback chain failed. Not billed. See [Errors](/docs/errors).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/tiktok/profile": {
      "get": {
        "operationId": "getTikTokProfile",
        "tags": [
          "TikTok"
        ],
        "summary": "Get profile",
        "description": "Look up a TikTok profile by username.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "TikTok handle, no `@`.",
            "example": "tiktok"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "tiktok"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/TikTokProfile"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "tiktok",
                  "data": {
                    "username": "tiktok",
                    "display_name": "TikTok",
                    "followers": 95800000,
                    "verified": true
                  },
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/tiktok/posts": {
      "get": {
        "operationId": "listTikTokPosts",
        "tags": [
          "TikTok"
        ],
        "summary": "List posts",
        "description": "List recent posts for a TikTok profile, newest first, pinned posts excluded.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "TikTok handle, no `@`.",
            "example": "tiktok"
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Number of posts to return. Default 20.",
            "example": 3
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "tiktok"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TikTokPost"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "tiktok",
                  "data": [
                    {
                      "id": "7680721699171601694",
                      "text": "this summer was all about the classic hits. here's to the ones that never got away 💿 #SongsofTheSummer2026",
                      "likes": 14200,
                      "comments": 2458
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/tiktok/post": {
      "get": {
        "operationId": "getTikTokPost",
        "tags": [
          "TikTok"
        ],
        "summary": "Get post",
        "description": "Fetch a single TikTok post/video by ID.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The post/video ID.",
            "example": "7680721699171601694"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "tiktok"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/TikTokPost"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "tiktok",
                  "data": {
                    "id": "7680721699171601694",
                    "text": "this summer was all about the classic hits. here's to the ones that never got away 💿 #SongsofTheSummer2026",
                    "likes": 14200,
                    "comments": 2458
                  },
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/tiktok/comments": {
      "get": {
        "operationId": "listTikTokComments",
        "tags": [
          "TikTok"
        ],
        "summary": "List comments",
        "description": "List comments on a TikTok post. `count` sets how many comments to return.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The post/video ID to fetch comments for.",
            "example": "7680721699171601694"
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Page size, confirmed exact on both providers.",
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "tiktok"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TikTokComment"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "tiktok",
                  "data": [
                    {
                      "id": "7680727229790126861",
                      "text": "yoo tiktok has tiktok",
                      "likes": 665
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/tiktok/search": {
      "get": {
        "operationId": "searchTikTok",
        "tags": [
          "TikTok"
        ],
        "summary": "Search users",
        "description": "Search TikTok creators by keyword.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Keyword to search users by.",
            "example": "tiktok"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "tiktok"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TikTokProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "tiktok",
                  "data": [
                    {
                      "username": "tiktokcreators",
                      "display_name": "tiktok creators",
                      "followers": 8826760,
                      "verified": true
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/tiktok/followers": {
      "get": {
        "operationId": "listTikTokFollowers",
        "tags": [
          "TikTok"
        ],
        "summary": "List followers",
        "description": "List a TikTok account's followers.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "TikTok handle, no `@`.",
            "example": "tiktok"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "tiktok"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TikTokProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "tiktok",
                  "data": [
                    {
                      "username": "h7505124",
                      "display_name": "H🧡",
                      "followers": 5,
                      "verified": false
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/tiktok/following": {
      "get": {
        "operationId": "listTikTokFollowing",
        "tags": [
          "TikTok"
        ],
        "summary": "List following",
        "description": "List who a TikTok account follows.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "TikTok handle, no `@`.",
            "example": "tiktok"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "tiktok"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TikTokProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "tiktok",
                  "data": [
                    {
                      "username": "tiktokcreators",
                      "display_name": "tiktok creators",
                      "followers": 8800000,
                      "verified": true
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/tiktok/discover": {
      "get": {
        "operationId": "discoverTikTok",
        "tags": [
          "TikTok"
        ],
        "summary": "Discover content",
        "description": "Search TikTok content by keyword or hashtag.\n\nThis is content search. `search` is TikTok **user** search; the two stay separate so each endpoint always returns one shape.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Keyword or #hashtag to search for.",
            "example": "cats"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "tiktok"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TikTokPost"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "tiktok",
                  "data": [
                    {
                      "id": "7687944192680660255",
                      "text": "Robert was out for me today 😂😭 #catsoftiktok #catlady #cats #fyp #foryoupage",
                      "likes": 63739,
                      "comments": 373
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/profile": {
      "get": {
        "operationId": "getXProfile",
        "tags": [
          "X"
        ],
        "summary": "Get profile",
        "description": "Look up an X (Twitter) profile by username.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "X handle, no `@`.",
            "example": "elonmusk"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/XProfile"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": {
                    "username": "elonmusk",
                    "display_name": "Elon Musk",
                    "followers": 241671501,
                    "verified": true
                  },
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/posts": {
      "get": {
        "operationId": "listXPosts",
        "tags": [
          "X"
        ],
        "summary": "List posts",
        "description": "List recent tweets for an X profile.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "X handle, no `@`.",
            "example": "elonmusk"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/XPost"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": [
                    {
                      "id": "2101767007406641574",
                      "text": "Cybertruck as Heavy Cav",
                      "likes": 6648,
                      "comments": 875
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/post": {
      "get": {
        "operationId": "getXPost",
        "tags": [
          "X"
        ],
        "summary": "Get post",
        "description": "Fetch a single tweet by ID.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The tweet ID.",
            "example": "1893456789012345678"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/XPost"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": {
                    "id": "2101767007406641574",
                    "text": "Cybertruck as Heavy Cav",
                    "likes": 6648,
                    "comments": 875
                  },
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/comments": {
      "get": {
        "operationId": "listXComments",
        "tags": [
          "X"
        ],
        "summary": "List comments",
        "description": "List replies to a tweet.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The tweet ID to fetch replies for.",
            "example": "1893456789012345678"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/XComment"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": [
                    {
                      "id": "2101808189197230387",
                      "text": "@elonmusk Fun Fact: The heaviest-duty Cybertruck variants can tow up to 11,000 pounds. \n\nHeavy cavalry checks out.",
                      "likes": 0
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/search": {
      "get": {
        "operationId": "searchX",
        "tags": [
          "X"
        ],
        "summary": "Search users",
        "description": "Search X users by keyword.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Keyword to search users by.",
            "example": "elonmusk"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/XProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": [
                    {
                      "username": "elonmusk",
                      "display_name": "Elon Musk",
                      "followers": 241671516,
                      "verified": true
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/followers": {
      "get": {
        "operationId": "listXFollowers",
        "tags": [
          "X"
        ],
        "summary": "List followers",
        "description": "List an X account's followers.\n\n`verified` reflects only X's legacy verification flag on this list, which reads `false` for almost every account. Use `profile` for real verification status.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "X handle, no `@`.",
            "example": "elonmusk"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/XProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": [
                    {
                      "username": "ripus3n",
                      "display_name": "rip",
                      "followers": 0,
                      "verified": false
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/following": {
      "get": {
        "operationId": "listXFollowing",
        "tags": [
          "X"
        ],
        "summary": "List following",
        "description": "List who an X account follows.\n\n`verified` reflects only X's legacy verification flag on this list, which reads `false` for almost every account. Use `profile` for real verification status.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "X handle, no `@`.",
            "example": "elonmusk"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/XProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": [
                    {
                      "username": "wholemars",
                      "display_name": "Whole Mars Catalog",
                      "followers": 2114984,
                      "verified": false
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/retweeters": {
      "get": {
        "operationId": "listXRetweeters",
        "tags": [
          "X"
        ],
        "summary": "List retweeters",
        "description": "List who retweeted a tweet.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The tweet ID.",
            "example": "2101767007406641574"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/XProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": [
                    {
                      "username": "EVDOZIT",
                      "display_name": "Bryan R🔋📡🚀🛰",
                      "followers": 494,
                      "verified": true
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/discover": {
      "get": {
        "operationId": "discoverX",
        "tags": [
          "X"
        ],
        "summary": "Discover content",
        "description": "Search X content by keyword or hashtag.\n\nThis is content search. `search` is X **user** search; the two stay separate so each endpoint always returns one shape.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Keyword or #hashtag to search for.",
            "example": "cats"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/XPost"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": [
                    {
                      "id": "2102095151535702226",
                      "text": "NET'S CATS FAMILY🖤🐱♎\nHBD na🥳🎂🎉\nWe're singing🎶\nWe're dancing🦀\nHBD to us all✌🏻😆✌🏻\n@netsiraphop \n\nNET AT MAMI SCREEN GLOW DAY\n#MamiScreenGlowDayWithNet \n#MamixNet\n#netsiraphop",
                      "likes": 0,
                      "comments": 0
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/x/community": {
      "get": {
        "operationId": "getXCommunity",
        "tags": [
          "X"
        ],
        "summary": "Get community",
        "description": "Get an X community's details and recent posts in one call.\n\nFans out to two upstream calls internally (details, then recent posts).\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community ID.",
            "example": "1493446837214187523"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "x"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/Community"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "x",
                  "data": {
                    "id": "1493446837214187523",
                    "name": "Build in Public",
                    "description": "Share what you're working on. Get feedback. Help each other move forward. – Sponsored by bolt.new ⚡",
                    "member_count": 267427,
                    "posts": [
                      {
                        "id": "2102173530553032851",
                        "text": "bought a 30g pack of cocoa krispies a few times. anyway i just carried a 1kg bag to checkout. never expected to end up buying cocoa krispies at all.\n\nbe like cocoa krispies on @RevenueCat",
                        "likes": 0,
                        "comments": 0
                      }
                    ]
                  },
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/profile": {
      "get": {
        "operationId": "getInstagramProfile",
        "tags": [
          "Instagram"
        ],
        "summary": "Get profile",
        "description": "Look up an Instagram profile by username.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Instagram handle, no `@`.",
            "example": "instagram"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/InstagramProfile"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": {
                    "username": "instagram",
                    "display_name": "Instagram",
                    "followers": 686706771,
                    "verified": true
                  },
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/posts": {
      "get": {
        "operationId": "listInstagramPosts",
        "tags": [
          "Instagram"
        ],
        "summary": "List posts",
        "description": "List recent posts for an Instagram profile.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Instagram handle, no `@`.",
            "example": "instagram"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InstagramPost"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "id": "3989102446432402227",
                      "text": "the smile says it all 🥹\n\n#InTheMoment\n\nVideo by @wurzeltheween \n\nMusic by Louis Prima",
                      "likes": 860541,
                      "comments": 10166
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/post": {
      "get": {
        "operationId": "getInstagramPost",
        "tags": [
          "Instagram"
        ],
        "summary": "Get post",
        "description": "Fetch a single Instagram post by ID.\n\nLike counts are live and can drift slightly between calls, even seconds apart. That's Instagram's real-time data, not a Fluxcrawl inconsistency.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The post ID.",
            "example": "3989102446432402227"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/InstagramPost"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": {
                    "id": "3989102446432402227",
                    "text": "the smile says it all 🥹\n\n#InTheMoment\n\nVideo by @wurzeltheween \n\nMusic by Louis Prima",
                    "likes": 860544,
                    "comments": 10166
                  },
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/comments": {
      "get": {
        "operationId": "listInstagramComments",
        "tags": [
          "Instagram"
        ],
        "summary": "List comments",
        "description": "List comments on an Instagram post.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The post ID to fetch comments for.",
            "example": "3989102446432402227"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InstagramComment"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "id": "17995953989821978",
                      "text": "Sooo sweet😊❤️❤️❤️❤️🍀",
                      "likes": 16
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/search": {
      "get": {
        "operationId": "searchInstagram",
        "tags": [
          "Instagram"
        ],
        "summary": "Search users",
        "description": "Search Instagram users by keyword.\n\n`followers` is always `0` here: Instagram's search response doesn't include a follower count, and hydrating every result would turn one call into N+1 upstream calls. If this request is served by the fallback provider, `verified` can read `false` for a verified account. Use `profile` when you need the verified status to be authoritative.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Keyword to search users by.",
            "example": "instagram"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock. Note: `followers` is always `0` here. Instagram's own search response doesn't carry a follower count, and hydrating each result with an extra profile lookup would turn one search call into N+1 upstream calls. See [Instagram](/docs/instagram).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InstagramProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "username": "instagram",
                      "display_name": "Instagram",
                      "followers": 0,
                      "verified": false
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/followers": {
      "get": {
        "operationId": "listInstagramFollowers",
        "tags": [
          "Instagram"
        ],
        "summary": "List followers",
        "description": "List an Instagram account's followers.\n\n`followers` is always `0` on listed rows, and `display_name` can be empty when an account hasn't set one. Use `profile` for full details.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Instagram handle, no `@`.",
            "example": "instagram"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InstagramProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "username": "rakesh_x53",
                      "display_name": "",
                      "followers": 0,
                      "verified": false
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/following": {
      "get": {
        "operationId": "listInstagramFollowing",
        "tags": [
          "Instagram"
        ],
        "summary": "List following",
        "description": "List who an Instagram account follows.\n\n`followers` is always `0` on listed rows, and `display_name` can be empty when an account hasn't set one. Use `profile` for full details.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Instagram handle, no `@`.",
            "example": "instagram"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InstagramProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "username": "adrienraza",
                      "display_name": "Adrien Raza",
                      "followers": 0,
                      "verified": true
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/likers": {
      "get": {
        "operationId": "listInstagramLikers",
        "tags": [
          "Instagram"
        ],
        "summary": "List likers",
        "description": "List who liked an Instagram post.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The post ID.",
            "example": "3989102446432402227"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InstagramProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "username": "lolo.snrj318",
                      "display_name": "",
                      "followers": 0,
                      "verified": false
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/discover": {
      "get": {
        "operationId": "discoverInstagram",
        "tags": [
          "Instagram"
        ],
        "summary": "Discover content",
        "description": "Search Instagram content by keyword or hashtag. Maps to a hashtag-media search. No plain-keyword search exists on this endpoint, only hashtag-based, so a leading `#` is optional and stripped.\n\nThis is content search. `search` is Instagram **account** search. Searching `cats` returns posts tagged `#cats`, not a keyword match across captions.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Keyword or #hashtag to search for.",
            "example": "cats"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InstagramPost"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "id": "3990060425716807185",
                      "text": "Throwback to the day I brought Phoebe home 🥲",
                      "likes": 976,
                      "comments": 15
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/highlights": {
      "get": {
        "operationId": "listInstagramHighlights",
        "tags": [
          "Instagram"
        ],
        "summary": "List highlights",
        "description": "List an Instagram account's story highlights.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Instagram handle, no `@`.",
            "example": "instagram"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Highlight"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "id": "highlight:18029499352961095",
                      "title": "what's new",
                      "media_count": 47
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/stories": {
      "get": {
        "operationId": "listInstagramStories",
        "tags": [
          "Instagram"
        ],
        "summary": "List stories",
        "description": "List an Instagram account's active stories.\n\nStories expire 24 hours after posting, so this returns an empty array for most accounts most of the time, not an error. No view count: Instagram doesn't expose one for accounts you don't own.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Instagram handle, no `@`.",
            "example": "instagram"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Story"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "id": "3991196691508326522",
                      "posted_at": "2026-09-21T16:22:20.000Z",
                      "expires_at": "2026-09-22T16:22:20.000Z"
                    }
                  ],
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/about": {
      "get": {
        "operationId": "getInstagramAbout",
        "tags": [
          "Instagram"
        ],
        "summary": "Get about",
        "description": "Get an Instagram account's transparency panel (join date, country, former usernames).\n\n`joined_date` is a plain \"Month Year\" string with no exact day. Don't parse it as ISO 8601.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Instagram handle, no `@`.",
            "example": "instagram"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/ProfileAbout"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": {
                    "joined_date": "February 2012",
                    "country": "United States",
                    "former_usernames": ""
                  },
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/locations": {
      "get": {
        "operationId": "listInstagramLocations",
        "tags": [
          "Instagram"
        ],
        "summary": "Search locations",
        "description": "Search Instagram locations near a coordinate. Not a name search: pass `lat` and `lng`.\n\n`posts` is always empty on search results, to avoid N+1 upstream calls. Pass a result's `id` to `location` to get that place's posts.\n\nReturns the first page only; pagination isn't exposed yet.\n\n**Cost:** 1 credit per successful call.",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Latitude.",
            "example": "40.7128"
          },
          {
            "name": "lng",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Longitude.",
            "example": "-74.0060"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock. `posts` is always empty here, see [Instagram](/docs/instagram).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Location"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": [
                    {
                      "id": "233608000157522",
                      "name": "New York, N Y",
                      "posts": []
                    }
                  ],
                  "meta": {
                    "credits_used": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/v1/instagram/location": {
      "get": {
        "operationId": "getInstagramLocation",
        "tags": [
          "Instagram"
        ],
        "summary": "Get location",
        "description": "Get an Instagram location's details and recent posts in one call.\n\n**Cost:** 2 credits per successful call.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The location ID (from `locations`' results, or Instagram's own location id).",
            "example": "233608000157522"
          }
        ],
        "responses": {
          "200": {
            "description": "Real, live data from the actual endpoint, not a mock.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "platform": {
                      "type": "string",
                      "enum": [
                        "instagram"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/Location"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "platform": "instagram",
                  "data": {
                    "id": "233608000157522",
                    "name": "New York, N Y",
                    "posts": [
                      {
                        "id": "3991393108048909265",
                        "text": "It's cool here come and join me 🌹🥰",
                        "likes": 1,
                        "comments": 0
                      }
                    ]
                  },
                  "meta": {
                    "credits_used": 2
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    }
  }
}
