# socially.run

> Social media data for AI agents and code.

socially.run reads public social media data from Instagram, TikTok, YouTube, LinkedIn, X, Facebook, GitHub and any web page, plus username searches across thousands of sites, email-to-accounts lookups, and country trend boards. One `so_` API key works across MCP (`https://api.socially.run/mcp`), the TypeScript/JavaScript SDK (`npm install socially`), REST (`https://api.socially.run/v1`), and the console (`https://console.socially.run`).

Every profile and post lookup returns HTTP 200 with `data.outcome`: `found`, `notFound` (authoritatively confirmed by the platform), or `undecided` (blocked, rate-limited, timed out, or unparseable; refunded and never cached). Never report `undecided` as "not found".

## Connect an AI agent (MCP)

The plugins sign in with OAuth. You hold no key.

Claude Code:

```bash
claude plugin marketplace add owe-br/plugins
claude plugin install socially@owe-br
```

Codex:

```bash
codex plugin marketplace add owe-br/plugins
codex plugin add socially@owe-br
codex mcp login socially
```

With an `so_` key from https://console.socially.run/keys (Claude Code):

```bash
claude mcp add --transport http socially https://api.socially.run/mcp \
  --header "Authorization: Bearer so_your_key"
```

## Reference files for LLMs and agents

- [Full LLM and agent reference](https://socially.run/llms-full.txt): MCP tools with full input schemas, SDK methods and REST routes
- [OpenAPI 3.1 specification](https://api.socially.run/openapi.json): REST reference, with x-mcp-tools
- [MCP guide and tool reference](https://socially.run/docs/en/mcp)
- [Quickstart](https://socially.run/docs/en)
- [TypeScript and JavaScript SDK](https://socially.run/docs/en/sdk)
- [REST API reference](https://socially.run/docs/en/api)
- [Authentication](https://socially.run/docs/en/authentication)
- [Errors and outcomes](https://socially.run/docs/en/errors)
- [Plans, credits and rate limits](https://socially.run/docs/en/limits)
- [Profiles and posts](https://socially.run/docs/en/profiles)
- [Batch lookups](https://socially.run/docs/en/batch)
- [Web pages and Open Graph](https://socially.run/docs/en/websites)
- [Trending and topic search](https://socially.run/docs/en/trending)
- [Username search](https://socially.run/docs/en/usernames)
- [Email lookup](https://socially.run/docs/en/emails)
- [Async jobs and streaming](https://socially.run/docs/en/jobs)
- [Webhooks](https://socially.run/docs/en/webhooks)