DataSocial API

openapi: 3.1.0
info:
  title: DataSocial API
  version: '2026-11-05'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-05: 15 operation(s) read from 13 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; DataSocial has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 2
    documentation: 13
    pages-with-code: 2
    pages-read: 13
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-05'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://datasocial.ai/playground
  - https://datasocial.ai/docs
  - https://datasocial.ai/keys
  - https://datasocial.ai/playground/user.posts
  - https://datasocial.ai/playground/user.info
  - https://datasocial.ai/playground/user.followers
  - https://datasocial.ai/playground/user.following
  - https://datasocial.ai/playground/user.recommended
  - https://datasocial.ai/playground/video.info
  - https://datasocial.ai/playground/video.comments
  - https://datasocial.ai/playground/video.comment_replies
  - https://datasocial.ai/playground/music.info
  - https://datasocial.ai/playground/music.posts
servers:
- url: https://api.datasocial.ai
paths:
  /mcp:
    get:
      operationId: get_mcp
      tags:
      - Mcp
      summary: GET /mcp
      x-source: https://datasocial.ai/keys
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl Run once in a terminal, then ask Claude about TikTok creators, videos or sounds. claude mcp add --transport http datasocial
          https://api.datasocial.ai/mcp  --header "Authorization: Bearer ds_live_YOUR_KEY" Need every row? Buy the full data . Privacy · Terms'
    post:
      operationId: post_mcp
      tags:
      - Mcp
      summary: 'The MCP server (Streamable HTTP): list_tables, describe_table, run_sql.'
      x-source: https://datasocial.ai/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMcpRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMcpResponse'
      x-evidence:
        kind: documentation
  /v1/ask:
    post:
      operationId: post_v1_ask
      tags:
      - Ask
      summary: A question in plain English → SQL, table, chart, note (checked but not run).
      x-source: https://datasocial.ai/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AskRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1AskResponse'
      x-evidence:
        kind: documentation
  /v1/data/sql:
    post:
      operationId: post_v1_data_sql
      tags:
      - Data
      summary: POST /v1/data/sql
      x-source: https://datasocial.ai/docs
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1DataSqlResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://api.datasocial.ai/v1/data/sql  -H \"Authorization: Bearer $DATASOCIAL_KEY\"  -H 'content-type: application/json'\
          \  -d '{\"sql\": \"SELECT username, followers FROM tiktok.creators WHERE country = '\\''US'\\'' ORDER BY followers DESC LIMIT 3\"}'\
          \ The response {\n \"columns\": [{ \"name\": \"username\", \"type\": \"String\" }, { \"name\": \"followers\", \"type\": \"UInt32\" }],\n\
          \ \"rows\": [[\"khaby.lame\", 162989705], ["
  /v1/music/info:
    get:
      operationId: get_v1_music_info
      tags:
      - Music
      summary: Detail for one sound
      x-source: https://datasocial.ai/playground/music.info
      parameters:
      - name: music_id
        in: query
        required: true
        schema:
          type: integer
        description: Numeric sound id.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1MusicInfoResponse'
      x-evidence:
        kind: documentation
  /v1/music/posts:
    get:
      operationId: get_v1_music_posts
      tags:
      - Music
      summary: Popular videos using a sound
      x-source: https://datasocial.ai/playground/music.posts
      parameters:
      - name: music_id
        in: query
        required: true
        schema:
          type: number
        description: Numeric sound id.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor.
      - name: count
        in: query
        required: false
        schema:
          type: integer
        description: Videos per page.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/tables:
    get:
      operationId: get_v1_tables
      tags:
      - Tables
      summary: Every table and column, with live row counts.
      x-source: https://datasocial.ai/docs
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1TablesResponse'
      x-evidence:
        kind: documentation
  /v1/user/followers:
    get:
      operationId: get_v1_user_followers
      tags:
      - User
      summary: List a creator's followers
      x-source: https://datasocial.ai/playground/user.followers
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: integer
        description: Numeric TikTok user id.
      - name: sec_user_id
        in: query
        required: false
        schema:
          type: string
        description: Strongly recommended. Get it from user.info or from any author object. Requests without it are noticeably less reliable.
      - name: count
        in: query
        required: false
        schema:
          type: integer
        description: Followers per page.
      - name: max_time
        in: query
        required: false
        schema:
          type: integer
        description: Pagination cursor. Pass min_time from the previous response to get the next page.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1UserFollowersResponse'
      x-evidence:
        kind: documentation
  /v1/user/following:
    get:
      operationId: get_v1_user_following
      tags:
      - User
      summary: List the accounts a creator follows
      x-source: https://datasocial.ai/playground/user.following
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: string
        description: Numeric TikTok user id.
      - name: sec_user_id
        in: query
        required: false
        schema:
          type: string
        description: Strongly recommended, as for user.followers.
      - name: count
        in: query
        required: false
        schema:
          type: string
        description: Accounts per page. TikTok answers up to 200 in one page.
      - name: max_time
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor.
      - name: page_token
        in: query
        required: false
        schema:
          type: string
        description: 'Next-page token: pass next_page_token from the previous response.'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1UserFollowingResponse'
      x-evidence:
        kind: documentation
  /v1/user/info:
    get:
      operationId: get_v1_user_info
      tags:
      - User
      summary: Full profile detail for one creator
      description: Returns the richest single‑user response TikTok's app API exposes, including follower/following counts, total likes, video
        count, bio text, verification state, region, commerce/business flags, bio email and linked accounts.
      x-source: https://datasocial.ai/playground/user.info
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: integer
        description: Numeric TikTok user id.
      - name: sec_user_id
        in: query
        required: false
        schema:
          type: string
        description: Optional opaque secondary id. Improves consistency when you have it.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/user/posts:
    get:
      operationId: get_v1_user_posts
      tags:
      - User
      summary: List a creator's videos
      x-source: https://datasocial.ai/playground
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: integer
        description: Numeric TikTok user id (not the @handle).
      - name: count
        in: query
        required: false
        schema:
          type: integer
        description: Videos per page. TikTok caps the real page size around 30-35 regardless of what you ask for.
      - name: max_cursor
        in: query
        required: false
        schema:
          type: integer
        description: Pagination cursor. Leave unset for the first page (defaults to the current epoch-millis); for the next page pass the max_cursor
          from the previous response.
      - name: min_cursor
        in: query
        required: false
        schema:
          type: integer
        description: Lower bound cursor. Leave at 0 unless you are walking backwards.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1UserPostsResponse'
      x-evidence:
        kind: documentation
  /v1/user/recommended:
    get:
      operationId: get_v1_user_recommended
      tags:
      - User
      summary: Accounts TikTok recommends alongside a creator
      x-source: https://datasocial.ai/playground/user.recommended
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: string
        description: Numeric TikTok user id to seed from.
      - name: sec_user_id
        in: query
        required: false
        schema:
          type: string
        description: Optional secondary id for the seed user.
      - name: count
        in: query
        required: false
        schema:
          type: string
        description: Recommendations to return.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/video/comments:
    get:
      operationId: get_v1_video_comments
      tags:
      - Video
      summary: Top-level comments on a video
      description: Pages through a video's comments. Each entry carries the comment text, like count, reply count, creation time and the commenter's
        user object, which makes comment listing a surprisingly good source of active-user discovery.
      x-source: https://datasocial.ai/playground/video.comments
      parameters:
      - name: aweme_id
        in: query
        required: true
        schema:
          type: string
        description: Numeric video id.
      - name: count
        in: query
        required: false
        schema:
          type: string
        description: Comments per page.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor. Pass the cursor from the previous response.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1VideoCommentsResponse'
      x-evidence:
        kind: documentation
  /v1/video/comments/replies:
    get:
      operationId: get_v1_video_comments_replies
      tags:
      - Video
      summary: Replies under one comment
      x-source: https://datasocial.ai/playground/video.comment_replies
      parameters:
      - name: aweme_id
        in: query
        required: true
        schema:
          type: number
        description: Numeric video id the parent comment belongs to.
      - name: comment_id
        in: query
        required: true
        schema:
          type: string
        description: cid of the parent comment, from video.comments.
      - name: count
        in: query
        required: false
        schema:
          type: string
        description: Replies per page.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1VideoCommentsRepliesResponse'
      x-evidence:
        kind: documentation
  /v1/video/info:
    get:
      operationId: get_v1_video_info
      tags:
      - Video
      summary: Full detail for a single video
      x-source: https://datasocial.ai/playground/video.info
      parameters:
      - name: aweme_id
        in: query
        required: true
        schema:
          type: integer
        description: Numeric video id.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1VideoInfoResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostMcpRequest:
      type: object
      properties:
        Authorization:
          type: string
          description: Bearer token for the key
      required:
      - Authorization
    PostMcpResponse:
      type: object
      properties:
        stream:
          type: string
          description: Streamable HTTP response containing tool output
    PostV1AskRequest:
      type: object
      properties:
        question:
          type: string
          description: Plain English question
      required:
      - question
    PostV1AskResponse:
      type: object
      properties:
        sql:
          type: string
          description: Generated SQL query
        table:
          type: string
          description: Suggested table for the answer
        chart:
          type: string
          description: Suggested chart type
        note:
          type: string
          description: Additional note
    PostV1DataSqlResponse:
      type: object
      properties:
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
        rows:
          type: array
          items:
            type: array
            items:
              type: string
        row_cap:
          type: integer
        capped:
          type: boolean
        rows_read:
          type: integer
        bytes_read:
          type: integer
        elapsed_ms:
          type: integer
    GetV1MusicInfoResponse:
      type: object
      properties:
        msg:
          type: string
          description: Message indicating success.
        status_code:
          type: integer
          description: Status code of the response.
        music_info:
          type: object
          description: Metadata for a single sound, including title, author, duration, cover art, play URL, and other attributes.
    GetV1TablesResponse:
      type: object
      properties:
        tables:
          type: array
          description: List of tables with column metadata and row counts
    GetV1UserFollowersResponse:
      type: object
      properties:
        extra:
          type: object
        followers:
          type: array
          description: Array of compact user objects.
        has_more:
          type: boolean
        log_pb:
          type: object
        max_time:
          type: integer
        min_time:
          type: integer
        myself_user_id:
          type: string
        next_page_token:
          type: string
        offset:
          type: integer
        status_code:
          type: integer
        status_msg:
          type: string
        total:
          type: integer
    GetV1UserFollowingResponse:
      type: object
      properties:
        extra:
          type: object
        followings:
          type: array
          description: List of following accounts.
        has_more:
          type: boolean
        log_pb:
          type: object
        max_time:
          type: integer
        min_time:
          type: integer
        myself_user_id:
          type: string
        next_page_token:
          type: string
        offset:
          type: integer
        rec_has_more:
          type: boolean
        status_code:
          type: integer
        status_msg:
          type: string
        total:
          type: integer
    GetV1UserPostsResponse:
      type: object
      properties:
        status_code:
          type: integer
        min_cursor:
          type: integer
        max_cursor:
          type: integer
        has_more:
          type: integer
        aweme_list:
          type: array
          description: List of video objects.
        extra:
          type: object
        log_pb:
          type: object
        has_locate_item:
          type: boolean
        filter_reasons:
          type: object
        status_msg:
          type: string
    GetV1VideoCommentsResponse:
      type: object
      properties:
        alias_comment_deleted:
          type: boolean
        comments:
          type: array
          description: List of comment objects (each with 36 keys).
        cursor:
          type: integer
        extra:
          type: object
        filtered_comments_count:
          type: integer
        filtered_comments_view_type:
          type: integer
        has_filtered_comments:
          type: integer
        has_more:
          type: integer
        log_pb:
          type: object
        reply_style:
          type: integer
        status_code:
          type: integer
        status_msg:
          type: string
        top_gifts:
          type: string
        total:
          type: integer
    GetV1VideoCommentsRepliesResponse:
      type: object
      properties:
        comments:
          type: array
          description: List of comment reply objects.
        cursor:
          type: integer
          description: Current pagination cursor.
        extra:
          type: object
          description: Additional metadata.
        has_more:
          type: integer
          description: Indicates if more pages are available.
        log_pb:
          type: object
          description: Log information.
        status_code:
          type: integer
          description: Response status code.
        status_msg:
          type: string
          description: Response status message.
        total:
          type: integer
          description: Total number of replies.
    GetV1VideoInfoResponse:
      type: object
      properties:
        aweme_detail:
          type: object
          description: Full video detail object.
        extra:
          type: object
          description: Additional metadata such as logid and timestamp.
        log_pb:
          type: object
          description: Log protobuf information.
        status_code:
          type: integer
          description: Status code of the response.
        status_msg:
          type: string
          description: Status message of the response.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Ask
- name: Data
- name: Mcp
- name: Music
- name: Tables
- name: User
- name: Video