socially-run Dossiers API

openapi: 3.2.0
info:
  title: 'socially.run: send a profile link, get its public data as…'
  version: 0.1.0
  description: 'One API for public data from Instagram, TikTok, YouTube, LinkedIn, X, Facebook, GitHub and any web page: profiles, posts, page text, username search, email lookup and trends. Every lookup answers **found**, **not found** or **we could not check** (`undecided`), never a guess, and a cached answer costs 0 credits. MCP tools share these operation definitions and the same `so_` key; x-mcp-tools lists the tools available over MCP. Writing TypeScript or JavaScript? `npm i socially` is one typed method per endpoint here.'
servers:
- url: https://api.socially.run/v1
tags:
- name: Dossiers
  description: 'The deep run: a full username sweep with the details each site exposes, delivered as one report.'
paths:
  /dossiers:
    post:
      operationId: create_dossier_post
      tags:
      - Dossiers
      summary: Build a dossier for a username
      description: 'A deeper pass than search_username: every claimed profile is read for the details it publishes (names, locations, avatars, bios, other identifiers and the usernames it links to), and those are collected into one report. Answers 202 with a job; the per-site rows are its hits and the report is its summary.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                username:
                  type: string
                  pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
                  description: The handle to build the dossier around.
                depth:
                  default: top500
                  description: top500 covers the highest-ranked sites; all covers the whole upstream database and takes several minutes.
                  type: string
                  enum:
                  - top500
                  - all
                recursion:
                  default: true
                  description: Follow usernames the claimed profiles link to, inside the same run. Turn it off for a narrower, faster dossier.
                  type: boolean
                includeNsfw:
                  default: false
                  description: Include adult sites. Requires a plan that allows them.
                  type: boolean
                includeUnreliable:
                  default: false
                  description: Also check sites the upstream database has marked unreliable.
                  type: boolean
              required:
              - username
      security:
      - bearerAuth: []
      responses:
        '202':
          description: Build a dossier for a username
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data: {}
        '400':
          description: 'VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: 'PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: 'RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.'
          headers:
            Retry-After:
              description: When present, how many seconds to wait before trying again.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        default:
          description: Any other failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-sdk:
        method: dossiers.create
        returns: JobDto
        repeatable: true
      x-credits: 30 credits; a deduped or cached dossier costs 0
components:
  schemas:
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: What went wrong, as a word a program can check.
            message:
              type: string
              description: What went wrong, as a sentence.
            messageKey:
              type: string
              description: '`message` as a key, to show it in your reader''s language, with `params` filling its blanks.'
            params:
              type: object
              additionalProperties:
                type:
                - string
                - number
              description: The values that fill `messageKey`'s blanks, such as a limit.
            details:
              description: More about this error, such as retryAfterSecs.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An `so_` API key from the console.
x-mcp-tools:
- name: resolve_target
  title: Resolve what a URL or @handle points at
  description: 'Turn a profile URL, post URL, website or @handle into what socially would read: the platform, the kind (profile, post, website), the normalized handle and the one canonical URL. No egress, no credit. Use it to validate input before a metered lookup.'
  inputSchema:
    type: object
    properties:
      input:
        type: string
        minLength: 1
        maxLength: 2048
        description: A profile URL, post URL, website or @handle.
      platform:
        description: Required when `input` is a bare handle.
        type: string
        enum:
        - instagram
        - linkedin
        - youtube
        - tiktok
        - x
        - facebook
        - github
        - website
    required:
    - input
    additionalProperties: false
- name: aggregate_intelligence
  title: Aggregate profiles into social intelligence
  description: 'Turn one or more profile reads (the six ExtractionResult keys) into the consolidated SocialIntelligence document: engagement, sentiment, content calendar, benchmark, a pt-BR knowledge-base markdown and personality hints. Pure and free. It only computes over what you send.'
  inputSchema:
    type: object
    properties:
      results:
        minItems: 1
        maxItems: 20
        type: array
        items:
          type: object
          properties:
            platform:
              type: string
              enum:
              - instagram
              - linkedin
              - youtube
              - tiktok
              - x
              - facebook
              - github
              - website
            url:
              type: string
            extractedAt:
              type: string
            profile:
              type: object
              properties:
                name:
                  type: string
                username:
                  type: string
                bio:
                  type: string
                followers:
                  type:
                  - number
                  - 'null'
                following:
                  type:
                  - number
                  - 'null'
                postsCount:
                  type:
                  - number
                  - 'null'
                profileUrl:
                  type: string
                avatarUrl:
                  type:
                  - string
                  - 'null'
                isVerified:
                  type:
                  - boolean
                  - 'null'
                isBusinessAccount:
                  type:
                  - boolean
                  - 'null'
                businessCategory:
                  type:
                  - string
                  - 'null'
                externalUrl:
                  type:
                  - string
                  - 'null'
              required:
              - name
              - username
              - bio
              - followers
              - following
              - postsCount
              - profileUrl
              - avatarUrl
            recentPosts:
              type: array
              items:
                type: object
                properties:
                  text:
                    type: string
                  date:
                    type:
                    - string
                    - 'null'
                  likes:
                    type:
                    - number
                    - 'null'
                  comments:
                    type:
                    - number
                    - 'null'
                  shares:
                    type:
                    - number
                    - 'null'
                  views:
                    type:
                    - number
                    - 'null'
                  url:
                    type:
                    - string
                    - 'null'
                  thumbnail:
                    type:
                    - string
                    - 'null'
                  duration:
                    type:
                    - string
                    - 'null'
                  hashtags:
                    type: array
                    items:
                      type: string
                  mediaType:
                    anyOf:
                    - type: string
                      enum:
                      - video
                      - image
                      - carousel
                      - article
                      - short
                      - reel
                    - type: 'null'
                required:
                - text
                - date
                - likes
                - comments
                - shares
                - views
                - url
            summary:
              type: string
          required:
          - platform
          - url
          - extractedAt
          - profile
          - recentPosts
          - summary
          additionalProperties: {}
    required:
    - results
    additionalProperties: false
- name: list_platforms
  title: List the platforms and how each one is answering
  description: List supported capabilities separately from source health. `capabilities` reports profile/post lookup, topic video search, indexed topic search, hashtag search and country trend boards. YouTube and TikTok support topic video search; only YouTube has a country board. Only Instagram has indexed topic search, the reels on its public popular page for a word, which exists for some words only. TikTok and Instagram support hashtag search. Google Trends is a separate `/trending` source. `status` and `strategies` describe profile reads; `postStatus` and `postStrategies` describe post reads, with verification dates and the last 24 hours of results. A supported capability can still have no working source here. Free.
  inputSchema:
    type: object
    properties: {}
    additionalProperties: false
- name: lookup_profile
  title: Look up a public profile
  description: 'Read a public profile on Instagram, TikTok, YouTube, LinkedIn, X, Facebook, GitHub or a website. A `found` answer includes the profile, recent posts and platform details when available: account ids, links, creation dates and public counts. Instagram''s `userId` and `graphId` name different ids; neither grants permission. Missing fields are null; unsupported blocks are absent. Data outcomes answer 200: `found`, `notFound` (confirmed by the platform, cached an hour) or `undecided` (refunded, never cached). 1 credit on a miss, 0 on a hit. `extractedAt` is the original read time, including cache and snapshot hits.'
  inputSchema:
    type: object
    properties:
      input:
        type: string
        minLength: 1
        maxLength: 2048
        description: A profile URL, post URL, website or @handle.
      platform:
        description: Required when `input` is a bare handle.
        type: string
        enum:
        - instagram
        - linkedin
        - youtube
        - tiktok
        - x
        - facebook
        - github
        - website
      posts:
        description: Recent posts to return (0–15). Default 10. This limits the answer, not the source read.
        type: integer
        minimum: 0
        maximum: 15
      refresh:
        description: Bypass the cache and the snapshot; costs a credit even when fresh.
        type: boolean
    required:
    - input
    additionalProperties: false
- name: lookup_profiles_batch
  title: Look up up to ten profiles in one call
  description: 'Read up to ten profiles at once (five in flight, 30 s each, 120 s total). Answers 200 with `results` (the found ones), `failures` (the ones not found and the ones we could not check, which are refunded) and, with `aggregate: true`, the consolidated social intelligence the siblings persist. `partial` says whether anything failed.'
  inputSchema:
    type: object
    properties:
      targets:
        minItems: 1
        maxItems: 10
        type: array
        items:
          type: object
          properties:
            input:
              type: string
              minLength: 1
              maxLength: 2048
              description: A profile URL, post URL, website or @handle.
            platform:
              description: Required when `input` is a bare handle.
              type: string
              enum:
              - instagram
              - linkedin
              - youtube
              - tiktok
              - x
              - facebook
              - github
              - website
          required:
          - input
          additionalProperties: false
        description: 1–10 profiles to read in parallel.
      posts:
        description: Recent posts to return (0–15). Default 10. This limits the answer, not the source read.
        type: integer
        minimum: 0
        maximum: 15
      aggregate:
        description: Run the aggregator over the profiles that were found (0 credits).
        type: boolean
      perTargetTimeoutMs:
        description: Per-profile timeout in milliseconds (1,000–30,000). Default 30,000.
        type: integer
        minimum: 1000
        maximum: 30000
    required:
    - targets
    additionalProperties: false
- name: lookup_post
  title: Look up a public post
  description: 'Read one public Instagram, TikTok, YouTube, X, LinkedIn or Facebook post or GitHub repository by URL. Returns its caption, author id, date, media and public counts when available. X, LinkedIn and Facebook posts are read only through a paid reader, with exact counts, and a deployment with no reader configured answers 503 before it charges. A LinkedIn post''s `author.profileUrl` is the person''s or the company''s own page, and a Facebook post''s `likes` counts every reaction. A full Instagram read adds source ids and ordered `frames` with image/video URLs, dimensions, duration and alt text; missing fields are null. YouTube adds video/channel ids, title and description, not a playable stream. GitHub adds repository details (language, license, default branch, topics, stars, forks, open issues and watchers). Every read says its `detailLevel` (`detailed` from the post''s own page or API, `embed` from a thin public card that leaves what it does not show null) and its `confidence`; a cached answer keeps both. CDN URLs can expire: download the files. Answers `found` or `undecided` (refunded), never `notFound`. 1 credit on a miss, 0 on a hit. Cached answers keep the original `extractedAt`.'
  inputSchema:
    type: object
    properties:
      url:
        type: string
        minLength: 1
        maxLength: 2048
        description: An http(s) URL.
      refresh:
        description: Bypass the cache and the snapshot; costs a credit even when fresh.
        type: boolean
    required:
    - url
    additionalProperties: false
- name: read_website
  title: Read a public web page
  description: 'Fetch a public page through the proxy and return its readable text, title, description, images and ld+json. Pages that render with JavaScript are rendered when the budget allows (`render: auto`). Private and internal addresses answer 400 SSRF_BLOCKED. 1 credit on a miss, 0 on a hit (24 h).'
  inputSchema:
    type: object
    properties:
      url:
        type: string
        minLength: 1
        maxLength: 2048
        description: An http(s) URL.
      maxChars:
        description: Cap on the readable text. Default 8,000.
        type: integer
        minimum: 500
        maximum: 50000
      render:
        description: '`always` renders every time and never falls back to a plain fetch. It spends render budget and fails closed at RENDER_BUDGET_EXHAUSTED; a deployment with no renderer answers SIDECAR_UNAVAILABLE.'
        type: string
        enum:
        - auto
        - never
        - always
      refresh:
        description: Bypass the cache and the snapshot; costs a credit even when fresh.
        type: boolean
    required:
    - url
    additionalProperties: false
- name: fetch_og
  title: Fetch a page's Open Graph card
  description: 'The Open Graph card a page publishes: title, description, image, site name, type, locale, canonical URL. 1 credit on a miss, 0 on a hit (24 h).'
  inputSchema:
    type: object
    properties:
      url:
        type: string
        minLength: 1
        maxLength: 2048
        description: An http(s) URL.
      refresh:
        description: Bypass the cache and the snapshot; costs a credit even when fresh.
        type: boolean
    required:
    - url
    additionalProperties: false
- name: get_job
  title: Get a job
  description: 'Read a job: its status, progress and credits, plus its hits once it has finished (found and undecided by default, capped at 500; page the rest with list_job_hits) and its summary. Poll this, or attach to the stream, until status is succeeded, partial, failed or cancelled.'
  inputSchema:
    type: object
    properties:
      id:
        type: string
        format: uuid
        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        description: The job id from the 202 that created it.
      include:
        description: Also embed the notFound hits (found and undecided come by default).
        type: string
        enum:
        - notFound
      wait:
        description: Wait up to this many seconds (0–25) for the job to settle before returning.
        type: integer
        minimum: 0
        maximum: 25
    required:
    - id
    additionalProperties: false
- name: list_job_hits
  title: List a job's hits
  description: Page through every site a job answered. It works while it is still running. Filter by outcome (found, notFound, undecided) or site category.
  inputSchema:
    type: object
    properties:
      id:
        type: string
        format: uuid
        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        description: The job id from the 202 that created it.
      outcome:
        description: Only hits with this outcome.
        type: string
        enum:
        - found
        - notFound
        - undecided
      category:
        description: Only sites in this category.
        type: string
        enum:
        - archived
        - art
        - blog
        - business
        - coding
        - dating
        - finance
        - gaming
        - health
        - hobby
        - images
        - misc
        - music
        - news
        - political
        - search
        - shopping
        - social
        - tech
        - video
        - xx NSFW xx
      limit:
        default: 50
        description: Hits per page (1–200). Default 50.
        type: integer
        minimum: 1
        maximum: 200
      offset:
        default: 0
        description: Rows to skip before this page. Default 0.
        type: integer
        minimum: 0
        maximum: 9007199254740991
    required:
    - id
    additionalProperties: false
- name: cancel_job
  title: Cancel a job
  description: Stop a job. A queued job is cancelled at once and fully refunded; a running one is asked to stop and lands within seconds. The hits it already has are kept and nothing is refunded. A finished job answers 409.
  inputSchema:
    type: object
    properties:
      id:
        type: string
        format: uuid
        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        description: The job id from the 202 that created it.
    required:
    - id
    additionalProperties: false
- name: search_username
  title: Search a username across the web
  description: 'Sweep the site database for one handle and report every site''s answer: found, notFound, or undecided when the site could not be read. Answers 202 with a job. Stream it or poll get_job. An identical search already running returns that same job and costs nothing.'
  inputSchema:
    type: object
    properties:
      username:
        type: string
        pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
        description: The handle to look for. Letters, digits, dot, dash and underscore.
      tier:
        default: fast
        description: fast sweeps the top-ranked sites inside a minute (5 credits); full sweeps the whole database (20 credits).
        type: string
        enum:
        - fast
        - full
      categories:
        description: Only sweep sites in these categories.
        maxItems: 21
        type: array
        items:
          type: string
          enum:
          - archived
          - art
          - blog
          - business
          - coding
          - dating
          - finance
          - gaming
          - health
          - hobby
          - images
          - misc
          - music
          - news
          - political
          - search
          - shopping
          - social
          - tech
          - video
          - xx NSFW xx
      sites:
        description: Only sweep these site ids (from list_username_sites).
        maxItems: 500
        type: array
        items:
          type: string
          minLength: 1
          maxLength: 100
      countries:
        description: Only sweep sites that serve these countries (ISO 3166-1 alpha-2). A site is kept when it serves any of them.
        maxItems: 50
        type: array
        items:
          type: string
          pattern: ^[A-Za-z]{2}$
      includeNsfw:
        default: false
        description: Include sites marked as adult. Requires a plan that allows them.
        type: boolean
      includeUnreliable:
        default: false
        description: Also sweep sites the nightly check distrusts. They answer, but never above low confidence.
        type: boolean
    required:
    - username
    additionalProperties: false
- name: list_username_sites
  title: List the sites a username search covers
  description: 'The site database: what each site is, how it is classified, how much a hit there is worth, and what the nightly check currently thinks of it. Use the ids to scope a search with `sites`.'
  inputSchema:
    type: object
    properties:
      category:
        description: Only sites in this category.
        type: string
        enum:
        - archived
        - art
        - blog
        - business
        - coding
        - dating
        - finance
        - gaming
        - health
        - hobby
        - images
        - misc
        - music
        - news
        - political
        - search
        - shopping
        - social
        - tech
        - video
        - xx NSFW xx
      includeNsfw:
        description: Include sites marked as adult in the listing.
        type: boolean
      limit:
        default: 50
        description: Sites per page (1–200). Default 50.
        type: integer
        minimum: 1
        maximum: 200
      offset:
        default: 0
        description: Rows to skip before this page. Default 0.
        type: integer
        minimum: 0
        maximum: 9007199254740991
    additionalProperties: false
- name: lookup_email
  title: Find where an email address is registered
  description: Ask ~119 services whether an address already has an account there, using each service's own signup or recovery check, never a password reset and never a message to the address. Answers 202 with a job. A service that rate-limits us answers undecided, never 'no account'. Requires a paid plan and an accepted acceptable-use policy.
  inputSchema:
    type: object
    properties:
      email:
        type: string
        maxLength: 254
        format: email
        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
        description: The address to look up. It is never messaged, only asked about. It is kept for as long as the job that reads it, and your history keeps a masked copy.
    required:
    - email
    additionalProperties: false
- name: create_dossier
  title: Build a dossier for a username
  description: 'A deeper pass than search_username: every claimed profile is read for the details it publishes (names, locations, avatars, bios, other identifiers and the usernames it links to), and those are collected into one report. Answers 202 with a job; the per-site rows are its hits and the report is its summary.'
  inputSchema:
    type: object
    properties:
      username:
        type: string
        pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
        description: The handle to build the dossier around.
      depth:
        default: top500
        description: top500 covers the highest-ranked sites; all covers the whole upstream database and takes several minutes.
        type: string
        enum:
        - top500
        - all
      recursion:
        default: true
        description: Follow usernames the claimed profiles link to, inside the same run. Turn it off for a narrower, faster dossier.
        type: boolean
      includeNsfw:
        default: false
        description: Include adult sites. Requires a plan that allows them.
        type: boolean
      includeUnreliable:
        default: false
        description: Also check sites the upstream database has marked unreliable.
        type: boolean
    required:
    - username
    additionalProperties: false
- name: list_trending
  title: Read what is trending in a country
  description: 'One country''s board: Google''s rising searches, each with the news behind it and an approximate volume, or YouTube''s most popular videos. A board stays fresh in the cache for ten minutes. A cached board costs 0 credits. When the source refuses us, the last good board is served instead, flagged `stale` with the time it was captured, and it costs nothing either: you are charged for a reading, never for an attempt.'
  inputSchema:
    type: object
    properties:
      source:
        default: google
        description: 'Which board to read: `google` for what a country is searching, `youtube` for what it is watching.'
        type: string
        enum:
        - google
        - youtube
      geo:
        type: string
        pattern: ^[A-Za-z]{2}$
        description: 'The country, ISO 3166-1 alpha-2 (US, BR, ES). REQUIRED: a board is one country''s board, and there is no honest default for whose. This used to fall back to `US`, which meant a caller in São Paulo was quietly handed the American one. A country the source does not publish answers 400 and says so. For a subject rather than a country, see `search_news` and `search_youtube`. A trending board takes no query.'
      category:
        description: 'YouTube''s video category id: `10` is Music, `17` Sport. YouTube only: Google Trends publishes no categories.'
        type: string
        minLength: 1
        maxLength: 20
      limit:
        default: 20
        description: Entries to return, 1–50. Google publishes ten per country.
        type: integer
        minimum: 1
        maximum: 50
    required:
    - geo
    additionalProperties: false
- name: search_youtube
  title: Search YouTube for videos on a subject
  description: 'What creators are publishing about a subject, in the order YouTube ranks it: title, channel, exact view count, duration and the description snippet, plus real upload dates, likes and comments when the deployment holds a Data API key (`stats: "exact"`). Read from the results page rather than the API''s 100-unit search, so one key''s day holds thousands of these. The answer is cached for thirty minutes, and the same question again costs nothing.'
  inputSchema:
    type: object
    properties:
      q:
        type: string
        minLength: 2
        maxLength: 200
        description: What to search for, the way you would type it into YouTube.
      limit:
        default: 10
        description: 'Videos to return, 1–20. One page is one read: a larger `limit` on the same question is served from it.'
        type: integer
        minimum: 1
        maximum: 20
      recency:
        description: 'Only videos uploaded within the window: `day`, `week`, `month` or `year`. Absent means any time.'
        type: string
        enum:
        - day
        - week
        - month
        - year
      sort:
        default: relevance
        description: '`relevance` uses YouTube''s ranking. `views` puts the most-watched videos first. Combine `views` with `recency` to find popular uploads within that window, not to measure growing views. Without a window, `views` includes all-time hits.'
        type: string
        enum:
        - relevance
        - views
      country:
        description: The country to rank for, ISO 3166-1 alpha-2 (BR, US, ES). Omit it for YouTube's own ranking rather than a country's.
        type: string
        pattern: ^[A-Za-z]{2}$
      language:
        description: The language to ask and read the page in, ISO 639-1 (en, pt, es). Omit it and your `accept-language` header decides.
        type: string
        pattern: ^[A-Za-z]{2}$
      refresh:
        description: Read the page again instead of serving the half-hour cache. Charged like any read, and the fresh answer replaces the cached one.
        type: boolean
    required:
    - q
    additionalProperties: false


# --- truncated at 32 KB (44 KB total) ---
# Full source: https://artifacts.apis.io/socially-run/openapi/socially-run-dossiers-api-openapi.yml