TikTok Research Video Search and Comments

arazzo: 1.0.1
info:
  title: TikTok Research Video Search and Comments
  summary: Search public videos by keyword and date range, then pull comments on the first matching video.
  description: >-
    Powers an academic research flow using the TikTok Research API. The workflow
    runs a boolean keyword search constrained by region and a date range, and
    then, when at least one video matches, retrieves the full comment thread on
    the first result including comment text, like counts, and reply counts.
    Every step spells out its request inline, including the inline Bearer
    authorization, so the flow can be read and executed without opening the
    underlying OpenAPI description.
  version: 1.0.0
sourceDescriptions:
- name: researchApi
  url: ../openapi/tiktok-research-openapi.yml
  type: openapi
workflows:
- workflowId: research-search-and-comments
  summary: Search research videos, then list comments on the top match.
  description: >-
    Runs a boolean keyword video search over a date range and region, then lists
    the comments on the first matching video when one is found.
  inputs:
    type: object
    required:
    - accessToken
    - keyword
    - startDate
    - endDate
    properties:
      accessToken:
        type: string
        description: OAuth 2.0 client-credentials token for the Research API.
      keyword:
        type: string
        description: Keyword to search video descriptions and captions for.
      regionCode:
        type: string
        description: ISO region code to constrain the search to.
        default: US
      startDate:
        type: string
        description: Start date in YYYYMMDD format.
      endDate:
        type: string
        description: End date in YYYYMMDD format.
      videoFields:
        type: string
        description: Comma-separated video fields to return.
        default: id,create_time,username,region_code,video_description,music_id,like_count,comment_count,share_count,view_count,hashtag_names
      commentFields:
        type: string
        description: Comma-separated comment fields to return.
        default: id,video_id,text,like_count,reply_count,parent_comment_id,create_time
      maxVideoCount:
        type: integer
        description: Maximum number of videos to return (1-100).
        default: 100
      maxCommentCount:
        type: integer
        description: Maximum number of comments to return (1-100).
        default: 100
  steps:
  - stepId: searchVideos
    description: >-
      Run a boolean AND search matching the keyword and region within the date
      range, returning the requested video fields.
    operationId: queryResearchVideos
    parameters:
    - name: Authorization
      in: header
      value: Bearer $inputs.accessToken
    - name: fields
      in: query
      value: $inputs.videoFields
    requestBody:
      contentType: application/json
      payload:
        query:
          and:
          - field_name: keyword
            operation: IN
            field_values:
            - $inputs.keyword
          - field_name: region_code
            operation: EQ
            field_values:
            - $inputs.regionCode
        start_date: $inputs.startDate
        end_date: $inputs.endDate
        max_count: $inputs.maxVideoCount
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      videos: $response.body#/data/videos
      topVideoId: $response.body#/data/videos/0/id
      hasMore: $response.body#/data/has_more
      searchId: $response.body#/data/search_id
    onSuccess:
    - name: haveResults
      type: goto
      stepId: listComments
      criteria:
      - context: $response.body
        condition: $.data.videos.length > 0
        type: jsonpath
    - name: noResults
      type: end
      criteria:
      - context: $response.body
        condition: $.data.videos.length == 0
        type: jsonpath
  - stepId: listComments
    description: >-
      Retrieve the comment thread on the first matching video, including text,
      like counts, and reply counts.
    operationId: listVideoComments
    parameters:
    - name: Authorization
      in: header
      value: Bearer $inputs.accessToken
    - name: fields
      in: query
      value: $inputs.commentFields
    requestBody:
      contentType: application/json
      payload:
        video_id: $steps.searchVideos.outputs.topVideoId
        max_count: $inputs.maxCommentCount
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      comments: $response.body#/data/comments
      hasMore: $response.body#/data/has_more
      cursor: $response.body#/data/cursor
  outputs:
    videos: $steps.searchVideos.outputs.videos
    topVideoId: $steps.searchVideos.outputs.topVideoId
    comments: $steps.listComments.outputs.comments