Unified Social Media API: One API for Public Social Data

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. Twenty-seven separate integrations can become twenty-seven separate systems.

The SocQ Social Media API puts public data behind one API key, one asynchronous task workflow, and a normalized record model. The current catalog contains 158 focused endpoints across 27 platforms: social networks, ad libraries, commerce, maps, app stores, and SEO.

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 source-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 a new authentication system and an incompatible response envelope for every source, 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 Marketplace listing is not an Instagram profile, and a Google Maps place has no useful equivalent on Reddit. 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.

27 Platforms and 158 Endpoints

Coverage is easier to reason about by category than by a short logo list.

Depth still matters more than a platform name. Instagram is not “one Instagram API.” TikTok Shop is not the TikTok video catalog. Review the API catalog for the accepted inputs and returned fields of each resource.

REST is one door. MCP, the CLI, and the Agent Skill are other doors into the same catalog. This article stays on the HTTP contract.

One Authentication and Task Pattern

All current catalog 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/x/search
POST /v1/linkedin/jobs
POST /v1/tiktok-shop/search
POST /v1/facebook-ad-library/search
POST /v1/google-maps/search

Inputs remain resource-specific. Profiles may accept usernames, known entities may require URLs, and search endpoints accept queries plus 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 the catalog:

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-09-09T08:00:00Z",
  "collected_at": "2026-09-10T08: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; a Shop result carries price and SKU context in extra. Model optional fields as nullable and branch on resource or type when source-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 or query, 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, LinkedIn reaction, ad impression, product sold count, and map rating 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. Ad libraries have creatives. Maps have places. 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 — or across Shop, Ad Library, and Maps — 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.

Request Examples across Categories

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"]}'

Search TikTok Shop:

curl -X POST "https://api.socq.ai/v1/tiktok-shop/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"region":"US"}'

Search the Facebook Ad Library:

curl -X POST "https://api.socq.ai/v1/facebook-ad-library/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"country":"US","status":"ACTIVE","media_type":"VIDEO","sort_by":"total_impressions"}'

Search Google Maps:

curl -X POST "https://api.socq.ai/v1/google-maps/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'

The authorization and task workflow remain the same; only valid resource inputs change. Platform-specific walkthroughs include TikTok, X, and SocQ MCP.

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 };
  "x/search": { query: string; results_limit?: number; sort_by?: "latest" | "top" };
  "linkedin/jobs": { urls: string[] };
  "tiktok-shop/search": { query: string; results_limit?: number; region?: string };
  "facebook-ad-library/search": { query: string; results_limit?: number; country?: string };
  "google-maps/search": { query: string; location: string; country?: 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
  product and listing fields
  place and review fields
  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 Native Platform 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 social networks.
• Influencer and creator research.
• Competitive content and creative analysis.
• Public Shop, Marketplace, and product research.
• Place and review collection.
• App-store and SEO datasets.
• AI-agent research tools that share one catalog.
• 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 the Catalog

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 or category 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 27 platforms return exactly the same fields?

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

Do I need one API key per platform?

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. Start from MCP if the client speaks that protocol.

What does the current catalog cover?

27 platforms and 158 endpoints across social networks, ad libraries, commerce, maps, app stores, and SEO. Check /apis for the live list.