InsightSocial Bluesky API

openapi: 3.2.0
info:
  title: Insightsocial App Bluesky API
  version: 2.0.0
  description: 'Operations tagged bluesky 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: Bluesky
paths:
  /v1/bluesky/profile:
    get:
      operationId: bluesky_profile
      summary: Profile
      description: 'Returns a Bluesky user''s public profile: handle, display name, avatar, description, follower and follows counts, post count, created date, and verification status.


        Use it when you have a handle and want the profile only; use user/posts for that account''s posts.


        **10 credits** per call.'
      tags:
      - Bluesky
      parameters:
      - name: handle
        in: query
        required: true
        description: Bluesky handle (e.g. `espn.com`).
        schema:
          type: string
          example: espn.com
      - 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/bluesky/user/posts:
    get:
      operationId: bluesky_user_posts
      summary: User › Posts
      description: 'Returns a feed of posts for a Bluesky user: text, author info, embeds, reply/repost/like/quote counts, and when each was indexed.


        Use it when you already have a handle or did and want that account''s own posts; use search to find posts by keyword instead.


        **10 credits** per call.'
      tags:
      - Bluesky
      parameters:
      - name: handle
        in: query
        required: false
        description: 'Bluesky handle. Provide at least one of: `handle`, `user_id`.'
        schema:
          type: string
          example: espn.com
      - name: user_id
        in: query
        required: false
        description: 'Bluesky `did` (Bluesky''s internal user ID format, e.g. `did:plc:x7d6j54pm22ufehkes6jo4jf`). Provide at least one of: `handle`, `user_id`.'
        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_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/bluesky/post:
    get:
      operationId: bluesky_post
      summary: Post
      description: 'Returns one Bluesky post: its record text, author info, embeds, reply count, repost count, like count, quote count, and a threaded replies array.


        Use it when you have a post URL; use user/posts to list everything one account has posted.


        **10 credits** per call.'
      tags:
      - Bluesky
      parameters:
      - name: url
        in: query
        required: true
        description: Bluesky post URL.
        schema:
          type: string
          example: https://bsky.app/profile/espn.com/post/3lqdfq7fkvm2g
      - 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: Post
      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/bluesky/search:
    get:
      operationId: bluesky_search
      summary: Search
      description: 'Returns Bluesky posts matching a keyword, up to 100 per page, each with its text, author, like/comment/share counts, and when it was written.


        Use it to find posts by keyword across all of Bluesky; use user/posts when you already know the account.


        **10 credits** per call.'
      tags:
      - Bluesky
      parameters:
      - name: query
        in: query
        required: true
        description: Search terms matched against post text.
        schema:
          type: string
          example: espresso
      - name: sort
        in: query
        required: false
        description: '`latest` (newest first, the default) or `top` (Bluesky''s own top ranking, which favours popular posts over recent ones).'
        schema:
          type: string
          enum:
          - latest
          - top
      - name: since
        in: query
        required: false
        description: Only posts written at or after this time. ISO 8601 date (`2026-09-01`) or datetime with a timezone (`2026-09-01T00:00:00Z`); any other shape is rejected with a free 400.
        schema:
          type: string
      - name: until
        in: query
        required: false
        description: Only posts written before this time. Same format as `since`. Set it to the oldest `published_at` of your last call to fetch the next older batch; the boundary is compared to the second, so a post from that same second can repeat, and deduplicating on `post.id` removes it.
        schema:
          type: string
      - name: lang
        in: query
        required: false
        description: Only posts tagged with this language, as a code such as `en`, `ja` or `ko`.
        schema:
          type: string
      - name: author
        in: query
        required: false
        description: 'Only posts by this account: a handle such as `espn.com` or a `did` such as `did:plc:...`. An account that does not exist returns an empty list.'
        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 120 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: 120
      - 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: Search
      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
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
    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)