InsightSocial Twitch API

openapi: 3.2.0
info:
  title: Insightsocial App Twitch API
  version: 2.0.0
  description: 'Operations tagged twitch across 2 of this provider''s published API definitions: openapi.json, insightsocial-app-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.insightsocial.app
security:
- apiKey: []
tags:
- name: Twitch
paths:
  /v1/twitch/profile:
    get:
      operationId: twitch_profile
      summary: Profile
      description: 'Returns a Twitch streamer''s public profile: display name, follower count, bio, profile image URL, broadcast language, and partner or affiliate status.


        Use it for a streamer''s public profile; use user/videos for their past broadcasts and highlights.


        **10 credits** per call.'
      tags:
      - Twitch
      parameters:
      - name: handle
        in: query
        required: true
        description: Twitch username
        schema:
          type: string
          example: ninja
      - name: max_age_s
        in: query
        required: false
        description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 900 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
        schema:
          type: integer
          minimum: 0
          maximum: 3600
      - name: dry_run
        in: query
        required: false
        description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
        schema:
          type: string
          enum:
          - '1'
      x-credits: 10
      x-group: Profile
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope2'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/ProfileOne'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
      x-stability: stable
    servers:
    - url: https://api.insightsocial.app
  /v1/twitch/clip:
    get:
      operationId: twitch_clip
      summary: Clip
      description: 'Returns one Twitch clip''s title, view count, duration, creator name, broadcaster name, game name, thumbnail URL, and creation timestamp.


        Use it when you have a clip URL and need its stats; use profile for the streamer''s own public info.


        **10 credits** per call.'
      tags:
      - Twitch
      parameters:
      - name: url
        in: query
        required: true
        description: Full URL of the Twitch clip
        schema:
          type: string
          example: https://www.twitch.tv/ninja/clip/BeautifulSolidYamOSkomodo-NXBFNORy-qFIXZ9R
      - name: max_age_s
        in: query
        required: false
        description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
        schema:
          type: integer
          minimum: 0
          maximum: 3600
      - name: dry_run
        in: query
        required: false
        description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
        schema:
          type: string
          enum:
          - '1'
      x-credits: 10
      x-group: Clip
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope2'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/PostOne'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
      x-stability: stable
    servers:
    - url: https://api.insightsocial.app
  /v1/twitch/user/videos:
    get:
      operationId: twitch_user_videos
      summary: User › Videos
      description: 'Returns up to 100 of a Twitch user''s videos: id, slug, URL, embed URL, title, view count, language, duration, game info, broadcaster details, thumbnail, and available qualities.


        Use it to list a streamer''s highlights and uploads; use clip for a single short clip''s own details.


        **10 credits** per call.'
      tags:
      - Twitch
      parameters:
      - name: handle
        in: query
        required: true
        description: Twitch username.
        schema:
          type: string
          example: ishowspeed
      - name: filter_by
        in: query
        required: false
        description: 'Filter the returned videos by type: `HIGHLIGHT` or `UPLOAD`. Past broadcasts are not available.'
        schema:
          type: string
          enum:
          - HIGHLIGHT
          - UPLOAD
      - name: sort_by
        in: query
        required: false
        description: 'Sort order: `TIME` (newest first) or `VIEWS`.'
        schema:
          type: string
          enum:
          - TIME
          - VIEWS
      - name: since
        in: query
        required: false
        description: 'Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept.'
        schema:
          type: string
      - name: until
        in: query
        required: false
        description: 'Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept.'
        schema:
          type: string
      - name: max_age_s
        in: query
        required: false
        description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
        schema:
          type: integer
          minimum: 0
          maximum: 3600
      - name: dry_run
        in: query
        required: false
        description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
        schema:
          type: string
          enum:
          - '1'
      x-credits: 10
      x-group: User
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope2'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/PostPage'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
      x-stability: stable
    servers:
    - url: https://api.insightsocial.app
  /v1/twitch/user/schedule:
    get:
      operationId: twitch_user_schedule
      summary: User › Schedule
      description: 'Returns a Twitch user''s upcoming stream schedule, each entry with start time, end time, title, description, and thumbnail URL.


        Use it to see when a streamer goes live next; use profile for their follower count and bio.


        **10 credits** per call.'
      tags:
      - Twitch
      parameters:
      - name: handle
        in: query
        required: true
        description: Twitch username.
        schema:
          type: string
          example: kaicenat
      - name: max_age_s
        in: query
        required: false
        description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
        schema:
          type: integer
          minimum: 0
          maximum: 3600
      - name: dry_run
        in: query
        required: false
        description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
        schema:
          type: string
          enum:
          - '1'
      x-credits: 10
      x-group: User
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope2'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/ConventionsData'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
      x-stability: beta
    servers:
    - url: https://api.insightsocial.app
components:
  schemas:
    Pagination:
      type: object
      properties:
        next_cursor:
          type:
          - string
          - 'null'
        has_more:
          type: boolean
        page_size:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        stopped_at:
          anyOf:
          - type: string
            enum:
            - since
            - known_id
            - end
          - type: 'null'
      required:
      - next_cursor
      - has_more
      - page_size
      additionalProperties: false
    ProfileOne:
      type: object
      properties:
        author:
          $ref: '#/components/schemas/Profile'
      required:
      - author
      additionalProperties: false
    Envelope2:
      type: object
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        schema_version:
          type: string
          const: '2'
        data: {}
        pagination:
          $ref: '#/components/schemas/Pagination'
        unavailable:
          type: array
          items:
            type: string
        credits_used:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        credits_remaining:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        request_id:
          type: string
        cached:
          type: boolean
        idempotent_replay:
          type: boolean
        charge_reason:
          type: string
        free_call:
          type: boolean
      required:
      - success
      - platform
      - endpoint
      - schema_version
      - data
      - unavailable
      - credits_used
      - credits_remaining
      - request_id
      - cached
      - idempotent_replay
      - charge_reason
      - free_call
      additionalProperties: false
    Author:
      type: object
      properties:
        id:
          anyOf:
          - type: string
            minLength: 1
            description: 'An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.'
          - type: 'null'
        username:
          type:
          - string
          - 'null'
        display_name:
          type:
          - string
          - 'null'
        avatar_url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        verified:
          type:
          - boolean
          - 'null'
      required:
      - id
      - username
      - display_name
      - avatar_url
      - verified
      additionalProperties: false
    ConventionsData:
      type: object
      propertyNames:
        type: string
        pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      x-stability: beta
    PostPage:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              post:
                $ref: '#/components/schemas/Post'
            required:
            - post
            additionalProperties: false
        total:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        truncated:
          type:
          - boolean
          - 'null'
        ext:
          anyOf:
          - type: object
            propertyNames:
              type: string
              pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
            additionalProperties:
              $ref: '#/components/schemas/JsonValue'
          - type: 'null'
          description: Platform-specific fields, snake_case. The key list per platform is in the docs.
      required:
      - items
      - total
      - truncated
      additionalProperties: false
    JsonValue:
      description: Any JSON value.
    Post:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: 'An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.'
        url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        kind:
          anyOf:
          - type: string
            minLength: 1
            description: The format of the post. Format words only, never a platform name. short = short-form vertical video (a reel, a TikTok, a YouTube Short).
            x-extensible-enum:
            - text
            - image
            - carousel
            - video
            - short
            - live
            - article
            - link
          - type: 'null'
        content:
          type: object
          properties:
            text:
              type:
              - string
              - 'null'
            media_urls:
              anyOf:
              - type: array
                items:
                  type: string
                  minLength: 1
                  format: uri
              - type: 'null'
            thumbnail_url:
              anyOf:
              - type: string
                minLength: 1
                format: uri
              - type: 'null'
            duration_seconds:
              anyOf:
              - type: number
                minimum: 0
              - type: 'null'
          required:
          - text
          - media_urls
          - thumbnail_url
          - duration_seconds
          additionalProperties: false
        author:
          $ref: '#/components/schemas/Author'
        engagement:
          type: object
          properties:
            views:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
            likes:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
            comments:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
            shares:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
            saves:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
          required:
          - views
          - likes
          - comments
          - shares
          - saves
          additionalProperties: false
        flags:
          type: object
          properties:
            nsfw:
              type:
              - boolean
              - 'null'
            spoiler:
              type:
              - boolean
              - 'null'
            pinned:
              type:
              - boolean
              - 'null'
            deleted:
              type: boolean
            likes_hidden:
              type:
              - boolean
              - 'null'
            comments_hidden:
              type:
              - boolean
              - 'null'
            shares_hidden:
              type:
              - boolean
              - 'null'
            views_hidden:
              type:
              - boolean
              - 'null'
            saves_hidden:
              type:
              - boolean
              - 'null'
          required:
          - nsfw
          - spoiler
          - pinned
          - deleted
          - likes_hidden
          - comments_hidden
          - shares_hidden
          - views_hidden
          - saves_hidden
          additionalProperties: false
        published_at:
          anyOf:
          - type: string
            format: date-time
            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            description: ISO-8601 timestamp in UTC, ending in Z.
          - type: 'null'
        language:
          anyOf:
          - type: string
            minLength: 2
            description: The content's language as the platform states it, e.g. en, pt-BR. Detected languages come later (§7.1).
          - type: 'null'
        ext:
          anyOf:
          - type: object
            propertyNames:
              type: string
              pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
            additionalProperties:
              $ref: '#/components/schemas/JsonValue'
          - type: 'null'
          description: Platform-specific fields, snake_case. The key list per platform is in the docs.
      required:
      - id
      - url
      - kind
      - content
      - author
      - engagement
      - flags
      - published_at
      - language
      - ext
      additionalProperties: false
    Error:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
            param:
              type: string
            top_up_url:
              type: string
          required:
          - type
          - message
          additionalProperties: false
        request_id:
          type: string
        credits_used:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        credits_remaining:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
      required:
      - success
      - error
      - request_id
      - credits_used
      - credits_remaining
      additionalProperties: false
    PostOne:
      type: object
      properties:
        post:
          $ref: '#/components/schemas/Post'
      required:
      - post
      additionalProperties: false
    Profile:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: 'An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.'
        username:
          type:
          - string
          - 'null'
        display_name:
          type:
          - string
          - 'null'
        avatar_url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        bio:
          type:
          - string
          - 'null'
        verified:
          type:
          - boolean
          - 'null'
        followers:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        followers_approximate:
          type:
          - boolean
          - 'null'
        following:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        posts_count:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        likes_count:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        location:
          type:
          - string
          - 'null'
        external_url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        private:
          type:
          - boolean
          - 'null'
        joined_at:
          anyOf:
          - type: string
            format: date-time
            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            description: ISO-8601 timestamp in UTC, ending in Z.
          - type: 'null'
        last_post_at:
          anyOf:
          - type: string
            format: date-time
            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            description: ISO-8601 timestamp in UTC, ending in Z.
          - type: 'null'
        ext:
          anyOf:
          - type: object
            propertyNames:
              type: string
              pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
            additionalProperties:
              $ref: '#/components/schemas/JsonValue'
          - type: 'null'
          description: Platform-specific fields, snake_case. The key list per platform is in the docs.
      required:
      - id
      - username
      - display_name
      - avatar_url
      - bio
      - verified
      - followers
      - followers_approximate
      - following
      - posts_count
      - likes_count
      - url
      - location
      - external_url
      - private
      - joined_at
      - last_post_at
      - ext
      additionalProperties: false
  responses:
    Error:
      description: See [Error handling](https://www.insightsocial.app/docs/errors).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              type: INSUFFICIENT_CREDITS
              message: 'This call needs up to 340 credits and 120 remain. Add credits: https://www.insightsocial.app/api/top-up?need=220&u=6f1c2b7e-0d4a-4c8e-9b21-3a5f7d9e1c40&via=api_402'
              top_up_url: https://www.insightsocial.app/api/top-up?need=220&u=6f1c2b7e-0d4a-4c8e-9b21-3a5f7d9e1c40&via=api_402
            request_id: req_1a2b3c4d5e6f
            credits_used: 0
            credits_remaining: 120
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your key from the dashboard. It starts with `isk_`.
x-refined-from:
- openapi.json
- insightsocial-app-openapi.json
x-provenance:
  method: harvested
  publisher: InsightSocial
  source: https://api.insightsocial.app/v1/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)