InsightSocial Snapchat API

openapi: 3.2.0
info:
  title: Insightsocial App Snapchat API
  version: 2.0.0
  description: 'Operations tagged snapchat 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: snapchat
paths:
  /v1/snapchat/profile:
    get:
      operationId: snapchat_profile
      summary: Profile
      description: 'Returns a Snapchat user''s public profile: display name, Bitmoji avatar URL, subscriber count, and bio description.


        Use it for a quick profile check; use spotlight/comments when you have a Spotlight snap URL instead.


        **10 credits** per call.'
      tags:
      - snapchat
      parameters:
      - name: handle
        in: query
        required: true
        description: Snapchat username
        schema:
          type: string
          example: djkhaled305
      - 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/snapchat/spotlight/comments:
    get:
      operationId: snapchat_spotlight_comments
      summary: Spotlight › Comments
      description: 'Returns comments on a Snapchat Spotlight snap: text, display name, reaction count, nested reply count, and timestamp.


        Use it when you have a Spotlight snap URL and want its comments; use profile for the poster''s own public info.


        **10 credits** per call.


        Paginates by `cursor`: see Pagination.'
      tags:
      - snapchat
      parameters:
      - name: url
        in: query
        required: true
        description: Full URL of the Snapchat Spotlight snap.
        schema:
          type: string
          example: https://www.snapchat.com/@lilah4823/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY2pvZnd0ZXVmAZ8fgG8pAZ8ff-_IAAAAAQ
      - name: cursor
        in: query
        required: false
        description: Cursor from the previous response to fetch the next page.
        schema:
          type: string
      - 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_pages
        in: query
        required: false
        description: 1 to 50 (default 1). Walk up to this many pages in one call and return the rows from all of them.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - 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 300 seconds old is served. 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: 300
      - 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: Spotlight
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope2'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/CommentPage'
        '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
components:
  schemas:
    CommentPage:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              comment:
                $ref: '#/components/schemas/Comment'
            required:
            - comment
            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
    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
    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
    Comment:
      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'
        parent_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'
        post_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'
        text:
          type:
          - string
          - 'null'
        author:
          $ref: '#/components/schemas/Author'
        engagement:
          type: object
          properties:
            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.
            replies:
              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:
          - likes
          - replies
          additionalProperties: false
        flags:
          type: object
          properties:
            pinned:
              type:
              - boolean
              - 'null'
            deleted:
              type: boolean
          required:
          - pinned
          - deleted
          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'
        replies:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/Comment'
          - 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
      - parent_id
      - post_id
      - text
      - author
      - engagement
      - flags
      - published_at
      - language
      - replies
      - ext
      additionalProperties: false
    JsonValue:
      description: Any JSON value.
    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
    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)