openapi: 3.0.0
info:
  title: Instagram Comments API
  description: |
    The Instagram Comments API retrieves the comments on a public Instagram post from its shortcode.

    Comments are returned a page at a time. Each response carries a `pagination.next_page_token`
    while more comments remain; pass it back as `next_page_token` to fetch the next page, and it is
    absent on the last page.

    Each comment includes its text, timestamp, like count and the author's public profile details.
    Comments posted as a GIF or sticker omit the text field and expose the image URL instead.
    A single shortcode identifies the media whatever its type, so photo posts, carousels, videos and reels are
    all fetched the same way.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Instagram Comments Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to 'instagram_comments' for Instagram Comments search
          schema:
            type: string
            enum: ["instagram_comments"]
            default: "instagram_comments"
        - name: post_id
          in: query
          required: true
          description: |
            Unique identifier for the Instagram post to fetch comments for. A post can
            be an image, carousel, or reel. You can find the identifier with the
            Instagram Profile API or in the post URL: `https://www.instagram.com/p/DbTmwYKFkZo/`
            uses `DbTmwYKFkZo`, and `https://www.instagram.com/reel/DbL6n0ggXDZ/` uses
            `DbL6n0ggXDZ`. The full post URL is also accepted.
          schema:
            type: string
            pattern: '^[A-Za-z0-9_-]{1,64}$'
          example: "DbTmwYKFkZo"
        - name: next_page_token
          in: query
          required: false
          description: |
            Opaque cursor for the next page of comments. Take it from `pagination.next_page_token`
            in a previous response and pass it back to page forward. Omit it for the first page.
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        post:
          $ref: '#/components/schemas/Post'
        comments:
          type: array
          description: Comments on the post for this page
          items:
            $ref: '#/components/schemas/Comment'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message when the post does not exist, is not public, or carries no comments
    SearchInformation:
      type: object
      description: Metadata about the result set. Present on the first page (absent on paginated responses).
      properties:
        total_results:
          type: integer
          description: Total number of comments on the post, across all pages
    Post:
      description: The post the comments belong to. Present on the first page (absent on paginated responses).
      allOf:
        - $ref: '#/components/schemas/Media'
        - type: object
          properties:
            caption:
              type: string
              description: Caption text of the post
            has_edited_caption:
              type: boolean
              description: Whether the caption was edited
            likes:
              type: integer
              description: Number of likes on the post
            has_like_and_view_counts_disabled:
              type: boolean
              description: Whether Instagram hides like and view counts
            comments:
              type: integer
              description: Number of comments on the post
            is_commenting_disabled:
              type: boolean
              description: Whether commenting is disabled for the viewer
            iso_date:
              type: string
              format: date-time
              description: Time the post was published, in UTC
            user:
              $ref: '#/components/schemas/User'
            location:
              $ref: '#/components/schemas/Location'
            coauthors:
              type: array
              items:
                $ref: '#/components/schemas/User'
            topics:
              type: array
              description: Topics Instagram relates to the post
              items:
                $ref: '#/components/schemas/Topic'
            carousel_items:
              type: array
              description: Carousel children in source order
              items:
                $ref: '#/components/schemas/CarouselItem'
    Media:
      type: object
      required: [id, media_id, type, permalink, link]
      properties:
        id:
          type: string
          description: Public media shortcode
        media_id:
          type: string
          description: Instagram's numeric media identifier
        type:
          type: string
          enum: [image, video, reel, carousel]
          description: Normalized media type
        permalink:
          type: string
          format: uri
          description: Public Instagram URL
        link:
          type: string
          format: uri
          description: Signed, time-limited direct image or video URL
        thumbnail:
          type: string
          format: uri
          description: Signed, time-limited media poster or preview image
        width:
          type: integer
          description: Original width in pixels
        height:
          type: integer
          description: Original height in pixels
        duration:
          type: number
          description: Video duration in seconds
        has_audio:
          type: boolean
          description: Whether a video carries audio
        accessibility_caption:
          type: string
          description: Instagram-provided accessibility description
        image_versions:
          type: array
          items:
            $ref: '#/components/schemas/ImageVersion'
        video_versions:
          type: array
          items:
            $ref: '#/components/schemas/VideoVersion'
        tagged_users:
          type: array
          items:
            $ref: '#/components/schemas/TaggedUser'
    CarouselItem:
      allOf:
        - $ref: '#/components/schemas/Media'
        - type: object
          required: [position]
          properties:
            position:
              type: integer
              description: Position in the carousel, starting at 1
    User:
      type: object
      properties:
        id:
          type: string
          description: Instagram user identifier
        username:
          type: string
          description: Instagram handle
        name:
          type: string
          description: Display name
        avatar:
          type: string
          format: uri
          description: Signed, time-limited profile image URL
        is_verified:
          type: boolean
          description: Whether the account is verified
        is_private:
          type: boolean
          description: Whether the account is private
        is_unpublished:
          type: boolean
          description: Whether the account is unpublished
    TaggedUser:
      allOf:
        - $ref: '#/components/schemas/User'
        - type: object
          properties:
            x:
              type: number
              description: Horizontal tag position
            y:
              type: number
              description: Vertical tag position
    ImageVersion:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
          description: Signed, time-limited image URL
        width:
          type: integer
        height:
          type: integer
    VideoVersion:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
          description: Signed, time-limited video URL
        type:
          type: integer
          description: Instagram media rendition type identifier
        width:
          type: integer
        height:
          type: integer
    Topic:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    Location:
      type: object
      description: Location tagged on the post. Absent when none is tagged
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        address:
          type: string
        city:
          type: string
        gps_coordinates:
          type: object
          properties:
            latitude:
              type: number
            longitude:
              type: number
        has_public_page:
          type: boolean
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Instagram post URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Engine used for the search
        post_id:
          type: string
          description: Shortcode of the requested Instagram post
        next_page_token:
          type: string
          description: Cursor echoed back when a page was requested with one
    Pagination:
      type: object
      properties:
        next_page_token:
          type: string
          description: Cursor for the next page of comments. Absent on the last page.
    Comment:
      type: object
      required: [position, id]
      properties:
        position:
          type: integer
          description: Position of the comment in the returned list, starting at 1
        id:
          type: string
          description: Unique identifier of the comment
        text:
          type: string
          description: Body of the comment. Absent on comments that carry only a GIF or sticker (see image)
        image:
          type: string
          description: URL of the GIF or sticker the comment was posted as. Absent on comments that carry text
        iso_date:
          type: string
          format: date-time
          description: Time the comment was posted, in UTC
        likes:
          type: integer
          description: Number of likes on the comment
        user:
          $ref: '#/components/schemas/CommentUser'
    CommentUser:
      type: object
      description: Public profile of the comment's author
      properties:
        id:
          type: string
          description: Unique identifier of the author
        username:
          type: string
          description: Instagram handle of the author
        is_verified:
          type: boolean
          description: Whether the author's account is verified. Absent when the account is not verified
        is_unpublished:
          type: boolean
          description: Whether the author's account is unpublished. Absent when the account is published
        avatar:
          type: string
          description: URL of the author's profile picture
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong