socially-run Profiles API
Read a public profile on Instagram, TikTok, YouTube, LinkedIn, X, Facebook, GitHub or a website, one at a time or in a batch, and aggregate the batch into one intelligence report.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/socially-run:socially-run-profiles-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
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: Profiles
description: Read a public profile on Instagram, TikTok, YouTube, LinkedIn, X, Facebook, GitHub or a website, one at a time or in a batch, and aggregate the batch into one intelligence report.
paths:
/intelligence/aggregate:
post:
operationId: aggregate_intelligence_post
tags:
- Profiles
summary: 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.'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
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
security:
- bearerAuth: []
responses:
'200':
description: Aggregate profiles into social intelligence
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: intelligence.aggregate
returns: SocialIntelligenceDto
repeatable: true
x-credits: 0 credits
/profiles/lookup:
post:
operationId: lookup_profile_post
tags:
- Profiles
summary: 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.'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
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
security:
- bearerAuth: []
responses:
'200':
description: Look up a public profile
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: profiles.lookup
returns: ProfileLookupResultDto
repeatable: true
x-credits: 1 credit on a cache miss, 0 on a hit; refunded when we could not check
/profiles/{platform}/{handle}:
get:
operationId: get_profile_get
tags:
- Profiles
summary: Get a public profile by platform and handle
description: The same lookup as `lookup_profile`, with the platform and handle in the URL path.
parameters:
- name: platform
in: path
required: true
schema:
type: string
enum:
- instagram
- linkedin
- youtube
- tiktok
- x
- facebook
- github
- website
- name: handle
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 100
- name: posts
in: query
required: false
description: Recent posts to return (0–15). Default 10. This limits the answer, not the source read.
schema:
description: Recent posts to return (0–15). Default 10. This limits the answer, not the source read.
type: integer
minimum: 0
maximum: 15
- name: refresh
in: query
required: false
description: Bypass the cache and the snapshot; costs a credit even when fresh.
schema:
description: Bypass the cache and the snapshot; costs a credit even when fresh.
type: boolean
security:
- bearerAuth: []
responses:
'200':
description: Get a public profile by platform and handle
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: profiles.get
returns: ProfileLookupResultDto
x-credits: 1 credit on a cache miss, 0 on a hit
/profiles/batch:
post:
operationId: lookup_profiles_batch_post
tags:
- Profiles
summary: 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.'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
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
security:
- bearerAuth: []
responses:
'200':
description: Look up up to ten profiles in one call
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: profiles.batch
returns: ProfileBatchDto
repeatable: true
x-credits: 1 per profile on a miss, 0 per hit; refunded for each profile we could not check
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
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://artifacts.apis.io/socially-run/openapi/socially-run-profiles-api-openapi.yml