Unified Social Media API: One API for 7 Platforms

Adding a second social platform to a product rarely doubles the integration work. Each network introduces a different authentication model, resource vocabulary, response shape, pagination scheme, error taxonomy, and maintenance schedule. Seven separate integrations can become seven separate systems.

The SocQ Social Media API puts public data from TikTok, Instagram, YouTube, Facebook, X, LinkedIn, and Reddit behind one API key, one asynchronous task workflow, and a normalized record model. The current catalog contains 32 focused endpoints across those seven platforms.

Quick answer: Call POST /v1/{platform}/{resource} with the inputs required by that resource, persist the returned task ID, and poll the common task endpoint. Records share normalized platform, resource, identity, author, metric, media, and timestamp conventions while retaining platform-specific values in explicit fields and extra.

What Is a Unified Social Media API?

A unified API is an abstraction layer over multiple platform integrations. Instead of teaching your application seven authentication systems and seven incompatible response envelopes, you integrate a shared contract and select the platform and resource in the route.

“Unified” should not mean “pretend every platform is identical.” A LinkedIn job is not a TikTok video, a subreddit is not an Instagram profile, and a YouTube transcript has no useful equivalent on Facebook. A responsible unified model standardizes concepts that are genuinely common and preserves source-specific semantics where they differ.

Public Data API vs Connected-Account API

Two different products appear in search results under “unified social media API.”

A connected-account API uses OAuth to let authorized users publish, schedule posts, manage comments or messages, and read private account insights. It is the right category for social media management software.

A public-data API collects supported publicly visible resources for research, monitoring, analytics, or enrichment. SocQ belongs to this second category. Its endpoints do not publish posts, send DMs, manage ads, or replace official APIs for authorized account actions.

Many products need both: official or connected-account APIs for writes and permissioned data, plus a public-data layer for supported external sources.

Seven Platforms and 32 Endpoints

The current SocQ catalog is:

Coverage depth matters more than a platform logo. Review the API catalog for the exact accepted inputs and returned fields of each resource.

One Authentication and Task Pattern

All current social endpoints use Bearer authentication:

Authorization: Bearer $SOCQ_API_KEY
Content-Type: application/json

Resource creation follows a predictable route:

POST /v1/{platform}/{resource}

Examples:

POST /v1/tiktok/profiles
POST /v1/instagram/reels
POST /v1/youtube/transcripts
POST /v1/facebook/comments
POST /v1/x/search
POST /v1/linkedin/jobs
POST /v1/reddit/subreddit-posts

Inputs remain resource-specific. Profiles may accept usernames, known entities may require URLs, and search endpoints accept queries and supported filters. A unified API should normalize operational behavior without forcing invalid inputs into one generic body.

The Shared Asynchronous Workflow

Long-running collection should not hold an HTTP connection open. SocQ creates a task:

Client
  └─ POST platform resource
       └─ task_id
            └─ poll common task endpoint
                 ├─ queued
                 ├─ running
                 ├─ succeeded → paginated records
                 └─ failed/cancelled → normalized error

Persist the task ID before polling. Use exponential backoff, treat queued and running as normal, process records only after success, and continue when the result indicates more pages.

This shared state machine means one worker can orchestrate all seven platforms:

def submit(platform, resource, payload):
    return post(f"/v1/{platform}/{resource}", json=payload)["data"]["task_id"]

def wait_for_task(task_id):
    while True:
        task = get(f"/v1/tasks/{task_id}")["data"]
        if task["status"] == "succeeded":
            return task
        if task["status"] in {"failed", "cancelled"}:
            raise CollectionError(task)
        backoff()

Production code should also persist cursors, cap retries, classify errors, and make downstream writes idempotent.

A Normalized Record Model

Where applicable, records use common conventions:

{
  "id": "source-id",
  "platform": "tiktok",
  "resource": "videos",
  "type": "video",
  "url": "https://source.example/item",
  "author": {
    "id": "author-id",
    "username": "creator",
    "name": "Creator"
  },
  "metrics": {
    "likes_count": 120,
    "comments_count": 8
  },
  "media": [],
  "created_at": "2026-07-18T08:00:00Z",
  "collected_at": "2026-07-19T08:00:00Z",
  "extra": {}
}

Not every resource has every field. A profile may expose name, description, and avatar_url; a post may use text; a video can have duration or audio; a job carries employment data. Model optional fields as nullable and branch on resource or type when platform-specific logic is required.

What Can Be Unified

Authentication

One SocQ API key can authenticate requests across the catalog.

Task lifecycle

Submission, polling, terminal states, pagination, and task observability can use one worker pattern.

Provenance

Every stored record should retain platform, resource, source URL, collection time, and source task ID.

Common entities

IDs, URLs, authors, public metrics, media references, publication times, and collection times can follow shared conventions where the source exposes them.

Error handling

Your application can map input validation, unavailable public resources, transient upstream failures, rate limits, and terminal collection failures into one internal taxonomy.

What Should Not Be Forced into One Shape

Metrics are not interchangeable

A TikTok play, Instagram view, YouTube view, X impression, Reddit score, and LinkedIn reaction can have different definitions and availability. Keep the original metric name instead of creating one misleading engagement number.

Resource depth differs

YouTube has transcripts and channels. LinkedIn has jobs and companies. Reddit has subreddits. TikTok has hashtags. A coverage matrix should expose these differences.

Discovery semantics differ

Search ranking, historical reach, localization, result limits, and freshness vary by platform. The same query across networks is not an apples-to-apples measurement.

Access and visibility differ

Public availability, deleted content, private accounts, age or region restrictions, and logged-in views are platform-specific. A unified API must not imply that access controls disappear.

Multi-Platform Request Examples

Collect TikTok profiles:

curl -X POST "https://api.socq.ai/v1/tiktok/profiles" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["tiktok","natgeo"]}'

Collect Instagram Reels:

curl -X POST "https://api.socq.ai/v1/instagram/reels" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["instagram"],"results_limit":50}'

Collect YouTube transcripts:

curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.youtube.com/watch?v=VIDEO_ID"]}'

Search Reddit:

curl -X POST "https://api.socq.ai/v1/reddit/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"developer tools","results_limit":100}'

The authorization and task workflow remain the same; only valid resource inputs change.

TypeScript Client Pattern

Use discriminated request types rather than an untyped generic payload:

type RequestMap = {
  "tiktok/profiles": { usernames: string[] };
  "instagram/reels": { usernames: string[]; results_limit?: number };
  "youtube/transcripts": { urls: string[] };
  "facebook/comments": { urls: string[] };
  "x/search": { query: string; limit?: number; sort?: "latest" | "top" };
  "linkedin/jobs": { urls: string[] };
  "reddit/search": { query: string; results_limit?: number };
};

async function submit<K extends keyof RequestMap>(
  endpoint: K,
  payload: RequestMap[K],
) {
  const response = await fetch(`https://api.socq.ai/v1/${endpoint}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) throw new Error(`SocQ ${response.status}`);
  return response.json();
}

Generate or maintain these types from an internal endpoint registry so documentation, validation, and clients cannot drift independently.

Database Design

A practical warehouse uses a common envelope plus resource tables:

social_record
  platform
  resource
  source_id
  canonical_url
  author_id
  created_at
  collected_at
  source_task_id
  raw_json

social_metric_snapshot
  platform
  resource
  source_id
  collected_at
  metric_name
  metric_value

resource-specific tables
  transcript segments
  job details
  profile attributes
  media metadata

Do not put every possible platform field into one 200-column table. Preserve the normalized envelope, then use typed resource tables or validated JSON for source-specific depth.

Error Normalization and Retries

Separate:

• Invalid input that will never succeed.
• Unsupported or unavailable public resources.
• Authentication and account errors.
• Rate or credit limits.
• Transient upstream failures.
• Provider bugs or schema validation failures.

Retry only transient classes. Use bounded exponential backoff with jitter. Record the attempt and task ID, and make upserts idempotent so a retry cannot duplicate records.

Unified API vs Seven Native APIs

This is not an all-or-nothing decision. Use native APIs for writes, owned analytics, and permissioned workflows; use a unified public-data API for supported public reads when that access model fits.

Common Use Cases

• Brand and topic monitoring across networks.
• Influencer and creator research.
• Competitive content analysis.
• AI-agent research tools.
• Social search and discovery.
• Comment, post, video, and transcript datasets.
• Public profile or company enrichment with appropriate safeguards.

Design the pipeline around the narrowest data necessary for the use case, not every field the source might expose.

When Not to Use a Unified Public-Data API

Do not use SocQ when:

• You need to publish, reply, send DMs, or manage ads.
• You need private account insights with user authorization.
• An official partner program is mandatory.
• A single platform-specific feature is essential and absent from the catalog.
• Your legal, contractual, or governance requirements prohibit the proposed collection.

The correct answer may be an official API, a connected-account provider, a licensed dataset, or no collection at all.

Migrate from One Platform to Seven

1. Define a normalized internal envelope before adding sources.
2. Integrate one high-value resource and preserve raw responses.
3. Validate IDs, timestamps, metrics, media, and null handling.
4. Add a second platform through the same task worker.
5. Keep source-specific adapters at the validation boundary.
6. Run old and new pipelines in parallel on a fixed sample.
7. Compare accepted unique records, freshness, and cost.
8. Migrate gradually and keep rollback paths.

Adding platforms becomes configuration work only after data meaning, observability, and failure handling are genuinely standardized.

Security, Privacy, and Responsible Use

Keep API keys in a secret manager, use least-privilege access to stored data, encrypt transport and storage, log administrative access, and define retention and deletion procedures.

Collect only supported public data needed for a legitimate purpose. Do not bypass private accounts, login barriers, audience controls, or other restrictions. Review platform terms, privacy obligations, intellectual-property rules, and applicable law. A unified technical interface does not unify or remove legal obligations.

FAQ

Does a unified social media API replace official APIs?

No. SocQ handles supported public reads. Official APIs remain necessary for publishing, OAuth user actions, private insights, and platform partner products.

Do all seven platforms return exactly the same fields?

No. They share normalized conventions where the concepts match, while resource-specific fields remain distinct.

Do I need seven API keys?

One SocQ key covers the SocQ catalog. Official or other provider integrations still require their own credentials.

Can SocQ publish social posts?

No. The current endpoints are read-only public-data operations.

How are rate limits handled?

Your application should respect the SocQ account limits, persist asynchronous task state, back off while polling, and retry only transient failures.

Is this suitable for AI agents?

Yes, when the agent uses typed tools, constrained inputs, task-state persistence, validation, and human approval for consequential downstream actions.

What are the seven supported platforms?

TikTok, Instagram, YouTube, Facebook, X/Twitter, LinkedIn, and Reddit.