Docs

v2 Unified Protocolhttps://api.soradar.app

API Reference

The Soradar Data API delivers a normalized, single-schema interface across TikTok, Instagram, Xiaohongshu, Lemon8, LinkedIn, YouTube, and Facebook. Built for developers, data engineers, and autonomous AI agents.

Jump to:Getting StartedAuthenticationCore ConceptsEndpoints ReferenceControl ParametersResponse HeadersErrors & Status CodesCredits & Metering
QuickstartBase URL: https://api.soradar.app

Getting Started

The Soradar API provides a unified, production-grade REST interface across 7 major social platforms: TikTok, Instagram, Xiaohongshu, Lemon8, LinkedIn, YouTube, and Facebook. Follow these steps to execute your first query in seconds.

Step 1: Obtain your API key

Authentication requires a Bearer token with the sk_live_ prefix. Free accounts are automatically credited with 300 requests upon registration.

Generate API Key
Step 2: Make your first request

Execute a GET request against the public user profile endpoint with your Bearer token:

cURLbash
curl -X GET "https://api.soradar.app/v2/tiktok/users/khaby.lame" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Step 3: The unified response envelope

Every entity returned by Soradar follows a normalized structure with stable identity fields, a decoupled metrics observation snapshot, and complete provenance tracking:

200 OK Responsejson
{
  "platform": "tiktok",
  "id": "khaby.lame",
  "handle": "khaby.lame",
  "displayName": "Khabane Lame",
  "url": "https://www.tiktok.com/@khaby.lame",
  "content": {
    "bio": "If you wanna laugh you are in the right place😎",
    "avatar": "https://p16-sign.tiktokcdn.com/tos-maliva-avt-0068/...",
    "verified": true,
    "location": "Italy"
  },
  "metrics": {
    "observedAt": 1740000000000,
    "followers": 162800000,
    "following": 78,
    "posts": 1240,
    "likes": 2400000000
  },
  "provenance": {
    "source": "tiktok:user:811c9d",
    "fetchedAt": 1740000000000,
    "fidelity": "detail"
  }
}
content

Stable platform metadata including bio, display name, verified status, and location.

metrics

Time-stamped observation snapshot with follower counts, likes, and engagement figures.

provenance

Record fidelity (summary vs detail), timestamp, and opaque source token.

Security

Authentication

All endpoints under /v2/ (with the exception of GET /v2/health) require HTTP Bearer token authentication. Your API tokens start with the sk_live_ prefix.

Passing your API Key

Pass your key in the standard Authorization header with the Bearer scheme:

HTTP Headerhttp
Authorization: Bearer sk_live_your_api_key_here
Key Lifetime & Scope

Tokens are perpetual until revoked. Each key is strictly bound to your tenant account, ensuring complete multi-tenant isolation and security.

Key Storage Invariant

Plaintext API keys are displayed once upon creation and never stored. Internal databases persist only SHA-256 cryptographic hashes.

Handling Authentication Rejections

Requests without a valid Bearer token will be rejected with an HTTP 401 Unauthorized (missing key) or 403 Forbidden (revoked or malformed key).

401 Unauthorized Responsejson
{
  "error": "auth_required",
  "message": "Authorization header required: Bearer <api_key>",
  "hint": "Authorization header required: Bearer <api_key>"
}
Architecture

Core Architectural Concepts

Soradar is engineered from the ground up to solve the core challenges of social data engineering: vendor heterogeneity, field truncation, volatile metrics, and LLM attention budgets.

1. One Shape Across All 7 Platforms

tiktokinstagramxiaohongshulemon8linkedinyoutubefacebook

Every platform represents creators, posts, comments, and engagement counters differently (e.g. TikTok uses numeric IDs in 64-bit space, Instagram uses shortcodes, Xiaohongshu uses 24-character hex strings). Soradar unifies these representations into an immutable, normalized TypeScript model where field names, data types, and structure are guaranteed identical across all seven networks.

2. Fidelity & Truncation Warnings

Every returned record declares its provenance fidelity: summary or detail, accompanied by a partialFields array listing any truncated fields.

Critical Production Example: Xiaohongshu (RED) Search

When searching Xiaohongshu notes via GET /v2/xiaohongshu/search/posts, the search index truncates note descriptions to 60 characters and omits structured tags entirely. Soradar flags these records with fidelity: "summary" and partialFields: ["text", "tags"]. To retrieve the full description and complete tag set, fetch the note by ID via GET /v2/xiaohongshu/posts/:id.

Summary Record with Partial Fieldsjson
{
  "platform": "xiaohongshu",
  "id": "64b8e1920000000012345",
  "content": {
    "title": "Top Shanghai Boutique Cafes",
    "text": "Exploring the best artisanal coffee roasters in the French Concession area..."
  },
  "provenance": {
    "source": "xiaohongshu:post:7a81df",
    "fidelity": "summary",
    "partialFields": ["text", "tags"]
  }
}

3. Entity vs. Observation (Append-Only Time Series)

Content is relatively stable, while engagement metrics fluctuate constantly. Soradar decouples immutable entity properties (handle, publication date, post body) from time-stamped metric observations.

Every metric object carries a mandatory observedAt epoch millisecond timestamp. Repeated queries over days and weeks append new observations rather than overwriting previous values. This turns your query history into a rich historical time series that powers velocity calculations, growth graphs, and creator performance medians available in the /stats endpoint.

4. The ?x-format=llm Attention Optimization

Standard JSON social responses are loaded with signed CDN media URLs (often 10+ URLs per video for mirrors and covers). These URLs are unfetchable by AI models lacking external network access, expire in ~48 hours, and consume up to 65% of the total token payload.

What is Omitted
  • Signed, expiring CDN media & video URLs
  • Raw avatar URLs and duplicate rendition mirrors
  • Platform-specific unstructured extras
What is Kept & Emphasized
  • Normalized metrics with explicit units
  • Inline truncation warnings on partial fields
  • Calculated engagement rates with explicit denominators
  • Media summarized cleanly by count and type (e.g. "1 video")
Markdown payload returned with ?x-format=llmmarkdown
# @charlidamelio (TikTok)
Followers: 151,800,000 | Following: 1,440 | Posts: 2,940 | Likes: 11,500,000,000
Verified: yes | Bio: hey :)

## Recent Posts
### Post 7315712989011242267
Published: 2026-01-01
Text: feeling grateful for all the love ✨
Media: 1 video (CDN media URLs omitted for model attention budget)
Metrics: 2.34M likes | 45.6M views | 156K comments | 89K shares | 42K collects
Engagement basis: 45,600,000 views (5.63% engagement rate)
Fidelity: detail

5. Credits-Based Metering

All API requests are priced in transparent credits. The credit consumption depends on the computational complexity and data scope of the target platform and endpoint (e.g. lightweight user profiles versus deep comment threads).

Every registered developer account starts with 300 free credits. You can verify your current balance and recent transactions at any time using the GET /v2/account/credits endpoint.

Reference

Endpoints Reference

Comprehensive documentation for all active endpoints on https://api.soradar.app. Every endpoint returns a structured JSON payload and standard diagnostic headers.

System & Capabilities

GET/v2/health
Public

Service liveness probe. Returns HTTP 200 with service version when operational.

cURLbash
curl -X GET "https://api.soradar.app/v2/health"
Responsejson
{
  "status": "healthy",
  "version": "2.0.0"
}
GET/v2/capabilitiesand/v2/capabilities/:platform
Bearer Auth

Dynamic capability introspection. Discovers supported platforms, slots, query parameters, and sort options programmatically.

cURLbash
curl -X GET "https://api.soradar.app/v2/capabilities/tiktok" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Responsejson
{
  "platform": "tiktok",
  "capabilities": [
    {
      "platform": "tiktok",
      "dataType": "user",
      "providers": ["tiktok:user:811c9d"],
      "params": {
        "id": { "type": "string", "required": true }
      }
    },
    {
      "platform": "tiktok",
      "dataType": "search_post",
      "providers": ["tiktok:search_post:2b4d9e"],
      "params": {
        "q": { "type": "string", "required": true },
        "limit": { "type": "number", "default": 20, "max": 50 },
        "sort": { "type": "string", "enum": ["relevance", "popular", "recent"] }
      }
    }
  ]
}

Users & Creators

GET/v2/:platform/users/:id
Bearer Auth

Retrieve a normalized user profile with current follower counts, bio, and verification status.

cURLbash
curl -X GET "https://api.soradar.app/v2/tiktok/users/khaby.lame" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Responsejson
{
  "platform": "tiktok",
  "id": "khaby.lame",
  "handle": "khaby.lame",
  "displayName": "Khabane Lame",
  "url": "https://www.tiktok.com/@khaby.lame",
  "content": {
    "bio": "If you wanna laugh you are in the right place😎",
    "avatar": "https://p16-sign.tiktokcdn.com/tos-maliva-avt-0068/...",
    "verified": true,
    "location": "Italy"
  },
  "metrics": {
    "observedAt": 1740000000000,
    "followers": 162800000,
    "following": 78,
    "posts": 1240,
    "likes": 2400000000
  },
  "provenance": {
    "source": "tiktok:user:811c9d",
    "fetchedAt": 1740000000000,
    "fidelity": "detail"
  }
}
GET/v2/:platform/users/:id/posts
Bearer Auth

Fetch a paginated list of posts authored by a creator. Accepts ?limit=, ?cursor=, and ?since= (epoch ms).

cURLbash
curl -X GET "https://api.soradar.app/v2/tiktok/users/khaby.lame/posts?limit=2" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Responsejson
{
  "items": [
    {
      "platform": "tiktok",
      "id": "7315712989011242267",
      "author": {
        "id": "khaby.lame",
        "handle": "khaby.lame",
        "displayName": "Khabane Lame"
      },
      "publishedAt": 1735730000000,
      "content": {
        "title": "When you try to open a door...",
        "text": "Life is simple, why complicate it? 😂 #comedy #lifehack",
        "tags": ["comedy", "lifehack"]
      },
      "metrics": {
        "observedAt": 1740000000000,
        "likes": 2340000,
        "views": 45600000,
        "shares": 89000,
        "comments": 156000
      },
      "provenance": {
        "source": "tiktok:user_posts:5d2a71",
        "fetchedAt": 1740000000000,
        "fidelity": "detail"
      }
    }
  ],
  "nextCursor": "cursor_eyJwYWdlIjoyfQ=="
}
GET/v2/:platform/users/:id/stats
Bearer Auth

Aggregated creator performance analytics over a time window. Accepts ?window= (7d, 30d, 90d — default 30d). Computes median views, median likes, engagement rates, and returns historical observation snapshots.

cURLbash
curl -X GET "https://api.soradar.app/v2/tiktok/users/khaby.lame/stats?window=30d" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Responsejson
{
  "platform": "tiktok",
  "userId": "khaby.lame",
  "window": "30d",
  "summary": {
    "followers": 162800000,
    "totalPostsInWindow": 24,
    "medianLikes": 1850000,
    "medianViews": 32000000,
    "medianComments": 94000,
    "engagementRateMedian": 0.058
  },
  "observations": [
    {
      "observedAt": 1737400000000,
      "followers": 162400000,
      "likes": 2390000000
    },
    {
      "observedAt": 1740000000000,
      "followers": 162800000,
      "likes": 2400000000
    }
  ],
  "limitations": []
}

Posts & Comments

GET/v2/:platform/posts/:id
Bearer Auth

Fetch complete post details by platform ID or shortcode with full caption text, media metadata, tags, and engagement counts.

cURLbash
curl -X GET "https://api.soradar.app/v2/instagram/posts/C8x9Kl10m" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Responsejson
{
  "platform": "instagram",
  "id": "C8x9Kl10m",
  "url": "https://www.instagram.com/p/C8x9Kl10m/",
  "author": {
    "id": "creativestudio",
    "handle": "creativestudio",
    "displayName": "Creative Studio"
  },
  "publishedAt": 1739800000000,
  "content": {
    "text": "Behind the scenes of our latest design sprint in Tokyo 🇯🇵 #design #architecture",
    "tags": ["design", "architecture"],
    "media": [
      {
        "type": "image",
        "url": "https://instagram.fsnc1-1.fna.fbcdn.net/v/..."
      }
    ]
  },
  "metrics": {
    "observedAt": 1740000000000,
    "likes": 48200,
    "comments": 612
  },
  "provenance": {
    "source": "instagram:post:9e120f",
    "fetchedAt": 1740000000000,
    "fidelity": "detail"
  }
}
GET/v2/:platform/posts/:id/comments
Bearer Auth

Retrieve a paginated list of comments for a post. Accepts ?limit= and ?cursor=.

cURLbash
curl -X GET "https://api.soradar.app/v2/instagram/posts/C8x9Kl10m/comments?limit=1" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Responsejson
{
  "items": [
    {
      "platform": "instagram",
      "id": "17992019481029482",
      "postId": "C8x9Kl10m",
      "author": {
        "id": "tokyocamera",
        "handle": "tokyocamera",
        "displayName": "Tokyo Street Photo"
      },
      "text": "The lighting in the second slide is absolutely stunning!",
      "publishedAt": 1739805000000,
      "metrics": {
        "observedAt": 1740000000000,
        "likes": 84
      },
      "provenance": {
        "source": "instagram:comment:8412ef",
        "fetchedAt": 1740000000000,
        "fidelity": "detail"
      }
    }
  ],
  "nextCursor": "cursor_comment_2"
}

Batch Processing

POST/v2/batch
Bearer Auth

Concurrently dispatch up to 25 requests in a single HTTP connection. Crucially, every batch item returns its own independent HTTP status code and response headers, ensuring that partial failures (e.g. one private profile among 20 public ones) do not fail the entire batch.

cURLbash
curl -X POST "https://api.soradar.app/v2/batch" \
  -H "Authorization: Bearer $SORADAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "id": "req-1", "path": "/v2/tiktok/users/khaby.lame" },
      { "id": "req-2", "path": "/v2/instagram/users/creativestudio" }
    ]
  }'
Responsejson
{
  "results": [
    {
      "id": "req-1",
      "status": 200,
      "headers": {
        "x-data-freshness": "fresh",
        "x-fidelity": "detail"
      },
      "body": {
        "platform": "tiktok",
        "id": "khaby.lame",
        "handle": "khaby.lame"
      }
    },
    {
      "id": "req-2",
      "status": 200,
      "headers": {
        "x-data-freshness": "cached",
        "x-fidelity": "detail"
      },
      "body": {
        "platform": "instagram",
        "id": "creativestudio",
        "handle": "creativestudio"
      }
    }
  ],
  "total": 2,
  "succeeded": 2,
  "failed": 0
}

Account & Metering

GET/v2/account/credits
Bearer Auth

Query current real-time credit balance and recent ledger audit entries for the authenticated tenant. Accepts ?limit= (max 50).

cURLbash
curl -X GET "https://api.soradar.app/v2/account/credits" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Responsejson
{
  "balanceCredits": 284,
  "balance_credits": 284,
  "recent": [
    {
      "id": "led_01jm9k...",
      "deltaCredits": -2,
      "delta_credits": -2,
      "reason": "usage:tiktok:user_posts",
      "createdAt": 1740000000000,
      "note": null
    },
    {
      "id": "led_01jm8a...",
      "deltaCredits": 300,
      "delta_credits": 300,
      "reason": "initial_grant",
      "createdAt": 1739900000000,
      "note": "Developer trial grant"
    }
  ]
}
GET/v2/account/usage
Bearer Auth

Query historical request volume, platform breakdowns, cache hit rates, and recent request logs. Accepts ?windowHours= (max 720 hours / 30 days), ?sinceTs=, ?nowTs=, and ?limit= (max 50).

cURLbash
curl -X GET "https://api.soradar.app/v2/account/usage?windowHours=24&limit=2" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Responsejson
{
  "window": {
    "sinceTs": 1739913600000,
    "untilTs": 1740000000000,
    "windowMs": 86400000,
    "label": "24h"
  },
  "requestCount": 16,
  "byPlatform": [
    {
      "platform": "tiktok",
      "requestCount": 12,
      "requests": 12,
      "upstreamCalls": 8,
      "cacheHits": 4
    },
    {
      "platform": "instagram",
      "requestCount": 4,
      "requests": 4,
      "upstreamCalls": 4,
      "cacheHits": 0
    }
  ],
  "recent": [
    {
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "ts": 1740000000000,
      "keyId": "key_01jh...",
      "platform": "tiktok",
      "dataType": "user",
      "outcome": "cache_hit",
      "upstreamCalls": 0,
      "latencyMs": 14,
      "itemsReturned": 1
    }
  ]
}
GET/v2/account/me

Returns tenant profile metadata (id, email, display_name, created_at).

GET/v2/account/keys

Lists active and revoked API keys for the authenticated tenant with key prefixes, creation dates, and request counts.

Parameters

Control Parameters

Control parameters are namespaced with the x- prefix. Unlike data query parameters (which define what to query and form the cache key), control parameters dictate how to execute or render the query without fragmenting the underlying cache.

ParameterTypeValuesDefaultDescription
x-cachestringbypass | stale-ok | onlystandardControls edge caching behavior. "bypass" forces a fresh upstream lookup; "stale-ok" allows serving stale cache for fastest latency; "only" returns cached content or 404 without hitting upstream.
x-formatstringjson | markdown | llmjsonOutput serialization format. "json" returns normalized data; "markdown" renders full human-readable prose; "llm" strips expired CDN media URLs, adds inline truncation warnings, and optimizes token density for AI agents.
x-describe-mediastring1 | 00Enables multimodal AI vision enrichment. When set to 1, images attached to posts are analyzed to generate factual descriptive captions.
x-session-idstringstring (max 128 chars)noneLogical task identifier (e.g. agent run ID or CI job ID) for grouping usage attribution. Can also be supplied via the X-Session-Id HTTP header.
x-session-budget-microsnumberpositive integerunlimitedSets a hard ceiling on credit consumption for the current session. Halts subsequent calls with an HTTP 402 session_budget_exhausted error if exceeded.
Telemetry

Response Headers

Soradar communicates freshness, fidelity, and request tracing via standard HTTP response headers. This keeps the data payload clean and canonical across caching layers.

HeaderExampleDescription
X-Request-Id550e8400-e29b-41d4-a716-446655440000Unique UUID trace identifier generated for every request. Included in server logs, rate-limit warnings, and error responses for rapid support diagnostics.
X-Data-Freshnessfresh | cached | staleIndicates data freshness. "fresh" means a live network fetch occurred; "cached" indicates a cache hit; "stale" indicates cached content served past freshness window.
X-Data-Age142Elapsed time in seconds since this record was retrieved from the platform and cached.
X-Fidelitysummary | detailCompleteness of the record. "summary" indicates search/list results with potentially truncated fields (see partialFields); "detail" indicates an exhaustive record.
X-Upstream-Calls1Total number of live provider network requests executed. Emits "0" on cache hits.
X-Data-Sourcetiktok:user:811c9dOpaque, non-reversible provider token identifying data origin without disclosing internal infrastructure or vendor identities.
X-Session-Idagent-run-2026-03-12Echoes back the client-supplied task session ID, confirming that cost attribution and session budget tracking are active for this call.
Reliability

Errors & Status Codes

Errors are treated as first-class product surfaces. Instead of opaque failure messages, every error payload carries an actionable hint designed to allow automated AI agents and human developers to self-heal and recover immediately.

Structured Error Format

All 4xx and 5xx responses emit a standard JSON object containing the error code, explanation, recovery guidance, and optional supported options:

Error Response Payloadjson
{
  "error": "unsupported_parameter",
  "message": "Invalid value 'compact' for 'x-format'. Supported values: json, markdown, llm",
  "hint": "Use ?x-format=json (default), ?x-format=markdown, or ?x-format=llm",
  "supported": ["json", "markdown", "llm"]
}
StatusCodeDescriptionActionable Recovery Hint
400unsupported_parameterA query or control parameter is invalid, malformed, or unrecognized.Inspect the "supported" array in the response to verify allowed parameter names and values.
401auth_requiredMissing or empty Authorization header.Provide an Authorization header formatted as: Bearer sk_live_...
402quota_exhaustedAccount balance has reached 0 credits.Top up credits in the dashboard or contact billing support.
402session_budget_exhaustedThe task reached the limit specified in x-session-budget-micros.This is a client-enforced cap. Report the partial results or initialize a new session.
403auth_invalidThe provided API key is invalid, expired, or has been revoked.Generate a new API key from the developer dashboard.
404not_foundThe requested user profile, post, shortcode, or comment was not found.Verify that the handle or resource ID is spelled correctly and is publicly accessible.
404unsupported_platformThe specified platform name is not recognized.Supported platforms: tiktok, instagram, xiaohongshu, lemon8, linkedin, youtube, facebook.
429rate_limitedRequest rate limit exceeded.Back off and retry using an exponential backoff algorithm with jitter.
501capability_disabledThe requested platform capability is temporarily disabled.Query GET /v2/capabilities to discover currently active slots.
503upstream_unavailableAll upstream data pipelines failed or circuit breaker is open.Retry after a short delay; inspect the Retry-After response header if present.
504timeoutThe upstream network timed out waiting for the target platform.Retry with a smaller ?limit= or a narrower ?since= query window.
Billing & Quotas

Credits & Metering

Soradar uses a credit-based metering system. Each request deducts credits from your tenant balance according to the target network and query depth.

Free Tier Grant
300 Credits

Every new developer account starts with 300 credits to test all 7 platforms.

Platform Granularity
Per-Endpoint

Lightweight profile queries use fewer credits; deep paginated comment threads use more.

Task Budgeting
Session Guard

Cap agent spend per task using x-session-budget-micros.

Programmatic Balance Inspection

Check your remaining balance and review recent ledger adjustments:

cURLbash
curl -X GET "https://api.soradar.app/v2/account/credits" \
  -H "Authorization: Bearer $SORADAR_API_KEY"
Account Credits Responsejson
{
  "balanceCredits": 284,
  "recent": [
    {
      "id": "led_01jm9k...",
      "deltaCredits": -2,
      "reason": "usage:tiktok:user_posts",
      "createdAt": 1740000000000,
      "note": null
    },
    {
      "id": "led_01jm8a...",
      "deltaCredits": 300,
      "reason": "initial_grant",
      "createdAt": 1739900000000,
      "note": "Developer trial grant"
    }
  ]
}
Need more credits or custom volume?
Manage your API keys, review hourly usage breakdowns, or top up your quota.
View Dashboard