xpoz-ai Instagram (live) API

openapi: 3.2.0
info:
  title: XPOZ Instagram (live) API
  version: 1.0.0
  description: 'Social media data API for Twitter/X, Instagram, Reddit, and TikTok.


    **Data endpoints** (`/api/data/*`) are authenticated with an API access key and are metered against the account''s credits. Most stored-data endpoints share the same query options: `fields` selects which attributes to return, `since`/`until` bound the date range, and `responseType` picks between a synchronous first page (`fast`), a full paged query run as a background operation (`paging`), and a CSV export (`csv`). `/live` endpoints fetch from the platform on demand and page with a cursor instead.


    **Account, billing, and crawl-settings endpoints** are used by the XPOZ dashboard and authenticate with the user''s session.'
servers:
- url: /
  description: This server
tags:
- name: Instagram (live)
  description: On-demand Instagram fetches straight from the platform, cursor-paginated. Not available for trial access keys.
paths:
  /api/data/instagram/posts/live:
    get:
      tags:
      - Instagram (live)
      summary: Search Instagram posts (live)
      description: Search Instagram posts on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/QueryQ'
      - $ref: '#/components/parameters/InstagramPostFields'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponse'
        '400':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramPostsLive
  /api/data/instagram/posts/users/{identifier}/live:
    get:
      tags:
      - Instagram (live)
      summary: Get an Instagram user's posts (live)
      description: Fetch an Instagram user's recent posts on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/Identifier'
      - $ref: '#/components/parameters/InstagramPostFields'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponse'
        '400':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramPostsUsersIdentifierLive
  /api/data/instagram/posts/{id}/live:
    get:
      tags:
      - Instagram (live)
      summary: Get an Instagram post (live)
      description: Fetch a single Instagram post on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/InstagramLivePostId'
      - $ref: '#/components/parameters/InstagramPostFields'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponse'
        '400':
          description: 'Validation failed. Also returned when the post ID is invalid: `Invalid Instagram post ID. Must be a shortcode (e.g., "DdaSlMIgeTm") or strong_id format: media_id_user_id (e.g., "3606450040306139062_4836333238").`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramPostsIdLive
  /api/data/instagram/posts/{id}/comments/live:
    get:
      tags:
      - Instagram (live)
      summary: Get Instagram post comments (live)
      description: Fetch top-level comments of an Instagram post on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/InstagramLivePostId'
      - $ref: '#/components/parameters/InstagramCommentFields'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponse'
        '400':
          description: 'Validation failed. Also returned when the post ID is invalid: `Invalid Instagram post ID. Must be a shortcode (e.g., "DdaSlMIgeTm") or strong_id format: media_id_user_id (e.g., "3606450040306139062_4836333238").`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramPostsIdCommentsLive
  /api/data/instagram/posts/{id}/comments/{commentId}/live:
    get:
      tags:
      - Instagram (live)
      summary: Get an Instagram comment (live)
      description: 'Fetch a single top-level comment of an Instagram post on demand, by post ID and comment ID. Always returns `has_more: false`. Reply (child comment) IDs are not supported; page the parent comment''s replies instead. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.'
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/InstagramLivePostId'
      - $ref: '#/components/parameters/InstagramCommentId'
      - $ref: '#/components/parameters/InstagramCommentFields'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponse'
        '400':
          description: 'Validation failed. Also returned when the post ID is invalid: `Invalid Instagram post ID. Must be a shortcode (e.g., "DdaSlMIgeTm") or strong_id format: media_id_user_id (e.g., "3606450040306139062_4836333238").`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramPostsIdCommentsCommentIdLive
  /api/data/instagram/posts/{id}/comments/{commentId}/replies/live:
    get:
      tags:
      - Instagram (live)
      summary: Get Instagram comment replies (live)
      description: Fetch replies to a top-level comment of an Instagram post on demand. Fetches directly from the platform and returns one page with a cursor, plus the top-level comment itself in `parent_comment`. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/InstagramLivePostId'
      - $ref: '#/components/parameters/InstagramCommentId'
      - $ref: '#/components/parameters/InstagramCommentFields'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstagramCommentRepliesCursorResponse'
        '400':
          description: 'Validation failed. Also returned when the post ID is invalid: `Invalid Instagram post ID. Must be a shortcode (e.g., "DdaSlMIgeTm") or strong_id format: media_id_user_id (e.g., "3606450040306139062_4836333238").`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramPostsIdCommentsCommentIdRepliesLive
  /api/data/instagram/posts/{id}/interacting-users/live:
    get:
      tags:
      - Instagram (live)
      summary: Get Instagram post interacting users (live)
      description: Fetch users who commented on or liked an Instagram post, on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/InstagramLivePostId'
      - $ref: '#/components/parameters/InstagramInteractionType'
      - $ref: '#/components/parameters/InstagramUserFields'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponse'
        '400':
          description: 'Validation failed. Also returned when the post ID is invalid: `Invalid Instagram post ID. Must be a shortcode (e.g., "DdaSlMIgeTm") or strong_id format: media_id_user_id (e.g., "3606450040306139062_4836333238").`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramPostsIdInteractingUsersLive
  /api/data/instagram/users/live:
    get:
      tags:
      - Instagram (live)
      summary: Search Instagram users (live)
      description: Search Instagram users by name on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/QueryName'
      - $ref: '#/components/parameters/InstagramUserFields'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponse'
        '400':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramUsersLive
  /api/data/instagram/users/{identifier}/live:
    get:
      tags:
      - Instagram (live)
      summary: Get an Instagram user (live)
      description: Fetch an Instagram user profile on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/Identifier'
      - $ref: '#/components/parameters/InstagramUserFields'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponse'
        '400':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramUsersIdentifierLive
  /api/data/instagram/users/{identifier}/connections/live:
    get:
      tags:
      - Instagram (live)
      summary: Get Instagram user connections (live)
      description: Fetch followers or following of an Instagram user on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/Identifier'
      - $ref: '#/components/parameters/ConnectionType'
      - $ref: '#/components/parameters/InstagramUserFields'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponse'
        '400':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataInstagramUsersIdentifierConnectionsLive
components:
  schemas:
    DataRouteError:
      type: object
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
          description: Endpoint-specific label, e.g. `Failed to retrieve Twitter posts`.
        error:
          type: string
          description: Detail. `An unexpected error occurred` for unhandled failures.
      required:
      - success
      - message
      - error
    DataSource:
      type: string
      enum:
      - database
      - api
      - hybrid
      description: Where the results came from.
    InstagramCommentRepliesCursorResponse:
      allOf:
      - $ref: '#/components/schemas/CursorResponse'
      - type: object
        properties:
          parent_comment:
            anyOf:
            - type: object
              additionalProperties: true
              description: The top-level comment the replies belong to, shaped by the requested `fields`.
            - type: 'null'
        required:
        - parent_comment
      description: Cursor envelope for Instagram comment replies, including the parent comment.
    SimpleError:
      type: object
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
      required:
      - success
      - message
    CursorResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            additionalProperties: true
            description: Entity shaped by the requested `fields`.
        count:
          type: integer
        dataSource:
          $ref: '#/components/schemas/DataSource'
        has_more:
          type: boolean
        next_page_cursor:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - results
      - count
      - dataSource
      - has_more
      - next_page_cursor
      description: 'Envelope for on-demand `/live` endpoints: one provider page plus a cursor.'
    TrialForbidden:
      type: object
      properties:
        success:
          type: boolean
          const: false
        code:
          type: string
          enum:
          - on_demand_not_available_in_trial
        message:
          type: string
      required:
      - success
      - code
      - message
  responses:
    TrialForbidden:
      description: On-demand search is not available for trial access keys.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TrialForbidden'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    DataRouteError:
      description: The request could not be fulfilled. Status is 400 for an empty or invalid search query, 402 when CSV export is blocked by plan limits, 500 otherwise.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataRouteError'
  parameters:
    QueryQ:
      name: q
      in: query
      required: true
      description: Search query (Lucene-style keyword syntax). Must not be blank.
      schema:
        type: string
    InstagramPostFields:
      name: fields
      in: query
      required: false
      description: 'Instagram post fields to return. Comma-separated. Allowed values: id, postType, userId, username, fullName, caption, mediaType, codeUrl, imageUrl, videoUrl, audioOnlyUrl, profilePicUrl, videoSubtitlesUri, subtitles, likeCount, commentCount, reshareCount, mediaRepostCount, saveCount, videoPlayCount, videoDuration, createdAt, createdAtTimestamp, createdAtDate, location, genAiChatWithAiCtaInfo, hasHighRiskGenAiInformTreatment.'
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - id
          - postType
          - userId
          - username
          - fullName
          - caption
          - mediaType
          - codeUrl
          - imageUrl
          - videoUrl
          - audioOnlyUrl
          - profilePicUrl
          - videoSubtitlesUri
          - subtitles
          - likeCount
          - commentCount
          - reshareCount
          - mediaRepostCount
          - saveCount
          - videoPlayCount
          - videoDuration
          - createdAt
          - createdAtTimestamp
          - createdAtDate
          - location
          - genAiChatWithAiCtaInfo
          - hasHighRiskGenAiInformTreatment
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque cursor from `next_page_cursor` of the previous page.
      schema:
        type: string
    InstagramCommentFields:
      name: fields
      in: query
      required: false
      description: 'Instagram comment fields to return. Comma-separated. Allowed values: id, text, parentPostId, parentPostUserId, type, parentCommentId, repliedToCommentId, childCommentCount, userId, username, fullName, likeCount, status, isSpam, hasTranslation, createdAt, createdAtTimestamp, createdAtDate, images.'
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - id
          - text
          - parentPostId
          - parentPostUserId
          - type
          - parentCommentId
          - repliedToCommentId
          - childCommentCount
          - userId
          - username
          - fullName
          - likeCount
          - status
          - isSpam
          - hasTranslation
          - createdAt
          - createdAtTimestamp
          - createdAtDate
          - images
    InstagramUserFields:
      name: fields
      in: query
      required: false
      description: 'Instagram user fields to return. Comma-separated. Allowed values: id, username, fullName, isPrivate, isVerified, followerCount, followingCount, mediaCount, biography, externalUrl, hasAnonymousProfilePicture, profilePicId, profilePicUrl, profileUrl.'
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - id
          - username
          - fullName
          - isPrivate
          - isVerified
          - followerCount
          - followingCount
          - mediaCount
          - biography
          - externalUrl
          - hasAnonymousProfilePicture
          - profilePicId
          - profilePicUrl
          - profileUrl
    ConnectionType:
      name: connectionType
      in: query
      required: true
      description: Which side of the follow graph to return.
      schema:
        type: string
        enum:
        - followers
        - following
    QueryName:
      name: name
      in: query
      required: true
      description: Name to search for. Must not be blank.
      schema:
        type: string
    Identifier:
      name: identifier
      in: path
      required: true
      description: User identifier; interpreted according to `identifierType` where supported, otherwise a username.
      schema:
        type: string
    InstagramInteractionType:
      name: interactionType
      in: query
      required: true
      description: Kind of interaction to list users for.
      schema:
        type: string
        enum:
        - commenters
        - likers
    InstagramCommentId:
      name: commentId
      in: path
      required: true
      description: ID of the top-level comment.
      schema:
        type: string
    InstagramLivePostId:
      name: id
      in: path
      required: true
      description: Instagram post shortcode (e.g. `DdaSlMIgeTm`, as in `instagram.com/p/DdaSlMIgeTm`) or strong ID in `media_id_user_id` format (e.g. `3606450040306139062_4836333238`).
      schema:
        type: string
        pattern: ^[A-Za-z0-9_-]+$
  securitySchemes:
    AccessKey:
      type: http
      scheme: bearer
      description: 'XPOZ API access key, created from the dashboard or `POST /api/tokens`. Send as `Authorization: Bearer <access key>`.'
    UserSession:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Descope session JWT of a logged-in dashboard user. Send as `Authorization: Bearer <session JWT>`.'