xpoz-ai TikTok (live) API

openapi: 3.2.0
info:
  title: XPOZ TikTok (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: TikTok (live)
  description: On-demand TikTok fetches straight from the platform, cursor-paginated. Not available for trial access keys.
paths:
  /api/data/tiktok/posts/live:
    get:
      tags:
      - TikTok (live)
      summary: Search TikTok posts (live)
      description: Search TikTok posts by keyword 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/TiktokPostFields'
      - $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: getDataTiktokPostsLive
  /api/data/tiktok/posts/hashtags/{hashtag}/live:
    get:
      tags:
      - TikTok (live)
      summary: Get TikTok posts by hashtag (live)
      description: Fetch posts carrying a hashtag 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/TiktokHashtag'
      - $ref: '#/components/parameters/TiktokPostFields'
      - $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: getDataTiktokPostsHashtagsHashtagLive
  /api/data/tiktok/posts/sounds/{sound}/live:
    get:
      tags:
      - TikTok (live)
      summary: Get TikTok posts by sound (live)
      description: Fetch posts using a sound 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/TiktokSound'
      - $ref: '#/components/parameters/TiktokPostFields'
      - $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: getDataTiktokPostsSoundsSoundLive
  /api/data/tiktok/posts/users/{identifier}/live:
    get:
      tags:
      - TikTok (live)
      summary: Get a TikTok user's posts (live)
      description: Fetch the posts of a TikTok user on demand, newest first. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/TiktokUsername'
      - $ref: '#/components/parameters/TiktokPostFields'
      - $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: getDataTiktokPostsUsersIdentifierLive
  /api/data/tiktok/posts/{id}/live:
    get:
      tags:
      - TikTok (live)
      summary: Get a TikTok post (live)
      description: 'Fetch a single TikTok post on demand. Always returns `has_more: false`. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.'
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/TiktokPostId'
      - $ref: '#/components/parameters/TiktokPostFields'
      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 TikTok post ID. Must be a numeric value (max 50 digits).`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataTiktokPostsIdLive
  /api/data/tiktok/posts/{id}/comments/live:
    get:
      tags:
      - TikTok (live)
      summary: Get TikTok post comments (live)
      description: Fetch top-level comments of a TikTok post on demand. TikTok may re-serve comments on later pages. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/TiktokPostId'
      - $ref: '#/components/parameters/TiktokLiveCommentFields'
      - $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 TikTok post ID. Must be a numeric value (max 50 digits).`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataTiktokPostsIdCommentsLive
  /api/data/tiktok/posts/{id}/comments/{commentId}/live:
    get:
      tags:
      - TikTok (live)
      summary: Get a TikTok comment (live)
      description: 'Fetch a single comment of a TikTok post on demand, by post ID and comment ID. Always returns `has_more: false`. Reliable for top-level comments; a reply is often not found, in which case 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/TiktokPostId'
      - $ref: '#/components/parameters/TiktokCommentId'
      - $ref: '#/components/parameters/TiktokLiveCommentFields'
      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 TikTok post ID. Must be a numeric value (max 50 digits).`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataTiktokPostsIdCommentsCommentIdLive
  /api/data/tiktok/posts/{id}/comments/{commentId}/replies/live:
    get:
      tags:
      - TikTok (live)
      summary: Get TikTok comment replies (live)
      description: Fetch replies to a top-level comment of a TikTok post on demand. Each reply carries `parentCommentId` (the top-level comment) and `replyToCommentId` (the reply it answers, `null` when it answers the top-level comment). The `replyCount` of the top-level comment can be higher than the number of replies served. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/TiktokPostId'
      - $ref: '#/components/parameters/TiktokCommentId'
      - $ref: '#/components/parameters/TiktokLiveCommentFields'
      - $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 TikTok post ID. Must be a numeric value (max 50 digits).`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TrialForbidden'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataTiktokPostsIdCommentsCommentIdRepliesLive
  /api/data/tiktok/users/live:
    get:
      tags:
      - TikTok (live)
      summary: Search TikTok users (live)
      description: Search TikTok users by name on demand. Results can overlap across pages. 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/TiktokUserFields'
      - $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: getDataTiktokUsersLive
  /api/data/tiktok/users/{identifier}/live:
    get:
      tags:
      - TikTok (live)
      summary: Get a TikTok user (live)
      description: 'Fetch a TikTok user profile by username on demand. Always returns `has_more: false`. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.'
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/TiktokUsername'
      - $ref: '#/components/parameters/TiktokUserFields'
      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: getDataTiktokUsersIdentifierLive
  /api/data/tiktok/users/{identifier}/connections/live:
    get:
      tags:
      - TikTok (live)
      summary: Get TikTok user connections (live)
      description: Fetch followers or following of a TikTok 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/TiktokUsername'
      - $ref: '#/components/parameters/ConnectionType'
      - $ref: '#/components/parameters/TiktokUserFields'
      - $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: getDataTiktokUsersIdentifierConnectionsLive
  /api/data/tiktok/sounds/live:
    get:
      tags:
      - TikTok (live)
      summary: Search TikTok sounds (live)
      description: Search TikTok sounds by keyword on demand. Results can overlap across pages. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - name: keyword
        in: query
        required: true
        description: Keyword to search for. Must not be blank.
        schema:
          type: string
      - $ref: '#/components/parameters/TiktokMusicFields'
      - $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: getDataTiktokSoundsLive
  /api/data/tiktok/hashtags/live:
    get:
      tags:
      - TikTok (live)
      summary: Search TikTok hashtags (live)
      description: Search TikTok hashtags by keyword on demand. Results can overlap across pages. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
      security:
      - AccessKey: []
      parameters:
      - name: keyword
        in: query
        required: true
        description: Keyword to search for. Must not be blank.
        schema:
          type: string
      - $ref: '#/components/parameters/TiktokHashtagFields'
      - $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: getDataTiktokHashtagsLive
components:
  parameters:
    TiktokPostFields:
      name: fields
      in: query
      required: false
      description: 'TikTok post fields to return. Comma-separated. Allowed values: id, postType, isPrivate, videoThumbnail, description, descriptionLanguage, userId, username, nickname, collectCount, commentCount, likeCount, downloadCount, forwardCount, playCount, hashtags, duration, videoUrl, transcriptsJson, createdAt, createdAtTimestamp, createdAtDate.'
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - id
          - postType
          - isPrivate
          - videoThumbnail
          - description
          - descriptionLanguage
          - userId
          - username
          - nickname
          - collectCount
          - commentCount
          - likeCount
          - downloadCount
          - forwardCount
          - playCount
          - hashtags
          - duration
          - videoUrl
          - transcriptsJson
          - createdAt
          - createdAtTimestamp
          - createdAtDate
    TiktokSound:
      name: sound
      in: path
      required: true
      description: TikTok sound (music) ID, or its exact track title.
      schema:
        type: string
    TiktokUserFields:
      name: fields
      in: query
      required: false
      description: 'TikTok user fields to return. Comma-separated. Allowed values: id, username, nickname, signature, secUid, avatar, isPrivate, isVerified, followerCount, followingCount, likeCount, postCount, language, region, createdAt, usernameModifyTime.'
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - id
          - username
          - nickname
          - signature
          - secUid
          - avatar
          - isPrivate
          - isVerified
          - followerCount
          - followingCount
          - likeCount
          - postCount
          - language
          - region
          - createdAt
          - usernameModifyTime
    TiktokUsername:
      name: identifier
      in: path
      required: true
      description: TikTok username, without the leading `@`.
      schema:
        type: string
    QueryQ:
      name: q
      in: query
      required: true
      description: Search query (Lucene-style keyword syntax). Must not be blank.
      schema:
        type: string
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque cursor from `next_page_cursor` of the previous page.
      schema:
        type: string
    TiktokHashtag:
      name: hashtag
      in: path
      required: true
      description: TikTok hashtag ID (numeric) or hashtag name without the leading `#`. Names must match a hashtag exactly.
      schema:
        type: string
    TiktokMusicFields:
      name: fields
      in: query
      required: false
      description: 'TikTok sound fields to return. Comma-separated. Allowed values: id, title, author, album, duration, userCount, isOriginal, isCommerceMusic, isOriginalSound.'
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - id
          - title
          - author
          - album
          - duration
          - userCount
          - isOriginal
          - isCommerceMusic
          - isOriginalSound
    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
    TiktokLiveCommentFields:
      name: fields
      in: query
      required: false
      description: 'TikTok live comment fields to return. Comma-separated. Allowed values: id, postId, userId, username, text, likeCount, createdAt, createdAtTimestamp, createdAtDate, imageUrls, stickerUrl, replyCount, parentCommentId, replyToCommentId. `replyCount` is the number of replies (`0` on replies), `parentCommentId` is the top-level comment a reply belongs to (`null` on top-level comments) and `replyToCommentId` is the reply a reply answers (`null` when it answers the top-level comment).'
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - id
          - postId
          - userId
          - username
          - text
          - likeCount
          - createdAt
          - createdAtTimestamp
          - createdAtDate
          - imageUrls
          - stickerUrl
          - replyCount
          - parentCommentId
          - replyToCommentId
    TiktokHashtagFields:
      name: fields
      in: query
      required: false
      description: 'TikTok hashtag fields to return. Comma-separated. Allowed values: id, name, viewCount, useCount, userCount, isCommerce.'
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - id
          - name
          - viewCount
          - useCount
          - userCount
          - isCommerce
    TiktokCommentId:
      name: commentId
      in: path
      required: true
      description: TikTok comment ID.
      schema:
        type: string
    TiktokPostId:
      name: id
      in: path
      required: true
      description: TikTok post ID (numeric, max 50 digits).
      schema:
        type: string
        pattern: ^\d{1,50}$
  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.
    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'
  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>`.'