openapi: 3.0.0
info:
  title: Instagram Post API
  description: |
    Retrieve a public Instagram photo, video, reel, or carousel from its shortcode.

    Responses include the caption, author, engagement, timestamp, direct media URLs,
    available image and video versions, video durations, comment previews, tags,
    topics, location, and coauthors when Instagram exposes those
    fields. Carousel children are returned in source order with their own media
    details. Direct Instagram CDN URLs are signed and can expire; repeat the search
    to retrieve fresh URLs.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Instagram Post Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to 'instagram_post' for Instagram post retrieval (photos, videos, reels, and carousels)
          schema:
            type: string
            enum: ["instagram_post"]
            default: "instagram_post"
        - name: post_id
          in: query
          required: true
          description: |
            Unique identifier for the Instagram post to retrieve. 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/DavpizrjugI/`
            uses `DavpizrjugI`, and `https://www.instagram.com/reel/DRaV7mnAGq7/` uses
            `DRaV7mnAGq7`. The full post URL is also accepted.
          schema:
            type: string
          example: "DavpizrjugI"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. A required query parameter is missing or invalid.
          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.
          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 the API key as a query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        post:
          $ref: '#/components/schemas/Post'
        error:
          type: string
          description: Error message when the post does not exist or is not public
    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 retrieve Instagram in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the response in seconds
        total_time_taken:
          type: number
          description: Total request and parsing time in seconds
        request_url:
          type: string
          format: uri
          description: Instagram media URL used for this search
        html_url:
          type: string
          format: uri
          description: URL to view the captured HTML
        json_url:
          type: string
          format: uri
          description: URL to retrieve the cached JSON response
    SearchParameters:
      type: object
      required: [engine, post_id]
      properties:
        engine:
          type: string
          enum: ["instagram_post"]
        post_id:
          type: string
          description: Shortcode of the requested Instagram media
    Post:
      allOf:
        - $ref: '#/components/schemas/Media'
        - type: object
          properties:
            caption:
              type: string
              description: Post caption
            has_edited_caption:
              type: boolean
              description: Whether the caption was edited
            likes:
              type: integer
              description: Number of likes
            has_like_and_view_counts_disabled:
              type: boolean
              description: Whether Instagram hides like and view counts
            comments:
              type: integer
              description: Number of comments
            is_commenting_disabled:
              type: boolean
              description: Whether commenting is disabled for the viewer
            iso_date:
              type: string
              format: date-time
              description: Publication time in UTC
            user:
              $ref: '#/components/schemas/User'
            location:
              $ref: '#/components/schemas/Location'
            coauthors:
              type: array
              items:
                $ref: '#/components/schemas/User'
            topics:
              type: array
              items:
                $ref: '#/components/schemas/Topic'
            carousel_items:
              type: array
              description: Carousel children in source order
              items:
                $ref: '#/components/schemas/CarouselItem'
            preview_comments:
              type: array
              description: Comment previews served with the post
              items:
                $ref: '#/components/schemas/PreviewComment'
            has_more_comments:
              type: boolean
              description: Whether more comments exist beyond the previews
    Media:
      type: object
      required: [id, media_id, type, permalink, link, thumbnail]
      properties:
        id:
          type: string
          description: Public media shortcode
        media_id:
          type: string
          description: Instagram's numeric media identifier
        permalink:
          type: string
          format: uri
          description: Public Instagram URL
        type:
          type: string
          enum: ["image", "video", "reel", "carousel"]
          description: Normalized media type
        link:
          type: string
          format: uri
          description: Signed, time-limited direct image or video URL
        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
        tagged_users:
          type: array
          items:
            $ref: '#/components/schemas/TaggedUser'
        image_versions:
          type: array
          items:
            $ref: '#/components/schemas/ImageVersion'
        video_versions:
          type: array
          items:
            $ref: '#/components/schemas/VideoVersion'
        thumbnail:
          type: string
          format: uri
          description: Signed, time-limited media poster or preview image
    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
      required: [username]
      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
    Location:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        gps_coordinates:
          type: object
          properties:
            latitude:
              type: number
            longitude:
              type: number
    Topic:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    PreviewComment:
      type: object
      required: [position, id, iso_date, user]
      properties:
        position:
          type: integer
          description: Position in the preview list, starting at 1
        id:
          type: string
          description: Instagram's numeric comment identifier
        text:
          type: string
          description: Comment text; absent for GIF and sticker comments
        image:
          type: string
          format: uri
          description: GIF or sticker image URL when the comment has no text
        iso_date:
          type: string
          format: date-time
          description: Comment time in UTC
        likes:
          type: integer
          description: Number of comment likes
        user:
          $ref: '#/components/schemas/User'
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong