fetcher-sh Instagram API

openapi: 3.2.0
info:
  title: fetcher.sh — web data API for agents Instagram API
  version: 1.0.0
  summary: 111 pay-per-call web-data endpoints across 11 services.
  description: 'Web data for agents and code: **111 endpoints across 11 services**, priced **$0.002 – $0.005 per call** in USDC on Base, Monad or Solana. No accounts, no OAuth, no subscriptions — you only pay for calls you make.


    Every endpoint is a `GET` returning the same envelope, where the HTTP status mirrors `status`:


    ```json

    { "status": 200, "message": "ok", "data": { } }

    ```


    ## Two ways to pay


    **1. Prepaid credits (simplest for code).** Top up once at https://fetcher.sh/topup, then send your key on every request:


    ```bash

    curl -H "Authorization: Bearer bby_live_..." "https://fetcher.sh/api/twitter/search?query=x402"

    ```


    **2. x402 per call (for autonomous agents).** Call without payment and you get `402` with machine-readable requirements in the `payment-required` header — one entry per supported network, so pay from whichever of Base, Monad or Solana you hold USDC on. Sign the authorization, retry with it, and the data comes back. Gas is sponsored, so the wallet needs no native token — libraries like `@x402/fetch` do the whole loop for you.


    ## Errors


    `400` invalid or missing parameter (the message names it) · `401` unknown or revoked key · `402` payment required, or `topup_required` when a balance is exhausted · `404` not a priced endpoint · `502` upstream failure. There are no rate limits; your balance is the only limit. Settlement happens before delivery, so failed upstream calls are not refunded.


    ## Also available


    MCP server for Claude, Cursor and other MCP clients · /skill.md agent setup instructions · /llms.txt condensed catalog · /topup create or recharge a key.'
  x-guidance: 'fetcher.sh is a web-data gateway: 111 read-only endpoints (Twitter / X, YouTube, TikTok, Instagram, Reddit, Google Search, Google Maps, Google News, Google Play, App Store, Yelp). Every endpoint is a GET request that returns the same JSON envelope: { status, message, data }, where the HTTP status mirrors the status field. Pricing is per call, $0.002 – $0.005 in USDC. There are no plans, subscriptions, or rate limits — your balance is the only limit. Payable on Base, Monad or Solana: every 402 lists one accepts entry per network (eip155:8453, eip155:143, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), each with its own USDC asset and payTo address, so pick the one matching a chain you hold USDC on. Base (eip155:8453) is always first. Two ways to pay. (1) x402 per call: request the endpoint, receive a 402 with machine-readable payment requirements, sign the USDC transfer authorization for your chosen network, and retry with the signed payload. Gas is sponsored by the facilitator, so the wallet needs no native token. (2) Prepaid credits: POST /api/credits/topup?amount=<usd> once (minimum $1, itself x402-paid) to receive a bby_live_ API key, then send it as `Authorization: Bearer <key>` on any endpoint — no signing and no chain round trip per call, which is much faster for high request volumes. GET /api/credits/balance returns the remaining balance for a key. Substitute path parameters marked {param}. Missing or invalid parameters return a descriptive 400. Settlement happens before delivery, so failed upstream calls are not refunded. Full agent setup instructions: /skill.md. Condensed catalog for LLMs: /llms.txt.'
  contact:
    email: info@fetcher.sh
servers:
- url: https://fetcher.sh
  description: Production
tags:
- name: Instagram
  description: Profiles, posts, reels, stories, followers, hashtags, locations, and comment threads.
paths:
  /api/instagram/audio/{id}/posts:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramAudioByIdPosts
      summary: Instagram — Audio posts
      description: Audio posts from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/hashtag/{name}/posts:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramHashtagByNamePosts
      summary: Instagram — Hashtag posts
      description: Hashtag posts from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/hashtag/{name}/reels:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramHashtagByNameReels
      summary: Instagram — Hashtag reels
      description: Hashtag reels from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/location/{id}/posts:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramLocationByIdPosts
      summary: Instagram — Location posts
      description: Location posts from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: tab
        in: query
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/post/code/{code}:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramPostCodeByCode
      summary: Instagram — Post code
      description: Post code from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/post/{id}/comments:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramPostByIdComments
      summary: Instagram — Post comments
      description: Post comments from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/user/handle/{handle}:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUserHandleByHandle
      summary: Instagram — User handle
      description: User handle from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: handle
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/user/search:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUserSearch
      summary: Instagram — User search
      description: User search from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/user/{id}:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUserById
      summary: Instagram — User
      description: User from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/user/{id}/followers:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUserByIdFollowers
      summary: Instagram — User followers
      description: User followers from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/user/{id}/followings:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUserByIdFollowings
      summary: Instagram — User followings
      description: User followings from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/user/{id}/posts:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUserByIdPosts
      summary: Instagram — User posts
      description: User posts from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/user/{id}/posts/tagged:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUserByIdPostsTagged
      summary: Instagram — User posts tagged
      description: User posts tagged from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/user/{id}/reels:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUserByIdReels
      summary: Instagram — User reels
      description: User reels from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/user/{id}/stories:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUserByIdStories
      summary: Instagram — User stories
      description: User stories from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /api/instagram/userid/{handle}:
    servers:
    - url: https://instagram.fetcher.sh
    get:
      operationId: instagramUseridByHandle
      summary: Instagram — Userid
      description: Userid from Instagram. Returns the standard { status, message, data } envelope. $0.004 per call, payable with x402 (USDC on Base, Monad or Solana) or a prepaid credits API key.
      tags:
      - Instagram
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004000'
        protocols:
        - x402: {}
      parameters:
      - name: handle
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Success — upstream payload in `data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Missing or invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          description: Payment Required
        '502':
          description: Upstream error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
components:
  schemas:
    Envelope:
      type: object
      description: Every response uses this envelope; the HTTP status mirrors `status`.
      properties:
        status:
          type: integer
          description: HTTP status code, mirrored in the body.
        message:
          type: string
          description: '"ok" on success, otherwise the error reason.'
        data:
          type:
          - object
          - array
          - 'null'
          description: Upstream payload; null on errors.
      required:
      - status
      - message
      - data