DocumentationAPI Reference
    Social APIs

    Social APIs

    Public TikTok, Facebook, and Instagram retrieval over the Desearch REST API.

    Use this page for platform search and lookups. For X, use the X API guide. For a natural-language answer that may include X posts, use AI Search with tools including "twitter".

    Who this page is for

    Humans

    Pick a platform, call the matching /desearch/{platform}/… route, then open API Reference for full schemas. Start with the search POST examples below; then profile, post/media, comments, or hashtag as needed.

    Agents / tool authors

    Use dedicated social tools when the caller needs exact platform objects (post, profile, comments, hashtag, TikTok trending).

    Do not substitute AI Search with a social-ish tool name - AI Search has no tools: ["tiktok"] / "facebook" / "instagram" family.

    For X operators, replies, retweeters, or trends, use the X API guide, not this hub. For NL multi-source evidence that may include X, use AI Search (tools may include "twitter").

    Which surface should I use?

    GoalUseNot this
    TikTok / Facebook / Instagram search and lookupsThis page + API ReferenceAI Search tools list
    X keyword ops, posts, replies, retweeters, trendsX API guide (GET /twitter…)Social hub paths
    NL prompt + ranked/summarized evidence (may include X)Search API POST /desearch/ai/search with tools including "twitter"Dedicated /twitter or social GETs when you need exact graphs
    X links only (no completion)POST /desearch/ai/search/links/twitterSocial hub

    Shared endpoint shape

    All three platforms expose the same shape (names differ slightly). Inventory matches live OpenAPI (19 paths).

    CapabilityTikTokInstagramFacebook
    SearchPOST /desearch/tiktok/searchPOST /desearch/instagram/searchPOST /desearch/facebook/search
    Single itemGET /desearch/tiktok/post/{id}GET /desearch/instagram/media/{id}GET /desearch/facebook/post/{id}
    ProfileGET /desearch/tiktok/profile/{username}GET /desearch/instagram/profile/{username}GET /desearch/facebook/profile/{profile_id}
    Profile postsGET /desearch/tiktok/profile/{username}/postsGET /desearch/instagram/profile/{username}/postsGET /desearch/facebook/profile/{profile_id}/posts
    CommentsGET /desearch/tiktok/comments/{video_id}GET /desearch/instagram/comments/{media_id}GET /desearch/facebook/comments/{post_id}
    HashtagGET /desearch/tiktok/hashtag/{tag}GET /desearch/instagram/hashtag/{tag}GET /desearch/facebook/hashtag/{tag}

    TikTok only: GET /desearch/tiktok/trending (optional region, count).

    Base URL: https://api.desearch.ai
    Auth: Authorization: $DESEARCH_API_KEY (raw key in examples).

    Usernames are without @. Hashtag path values are without #. Facebook profile_id accepts a public id or handle. Instagram media {id} accepts shortcode, id, or public URL where API Reference allows it.

    Platform notes (read before coding)

    TikTok

    • Search returns public posts by keyword. Post id is the canonical video ID for comments.
    • Not exposed: no-watermark / download-only media URLs.
    • Trending: GET /desearch/tiktok/trending.

    Instagram

    • Search returns public profiles by keyword (not a general media SERP).
    • Hashtag / media discovery: GET /desearch/instagram/hashtag/{tag}.
    • Media by id / shortcode / URL: GET /desearch/instagram/media/{id}.
    • Not exposed: private, login, posting, messaging, download-only surfaces.
    • Instagram trending is not exposed.

    Facebook

    • Search / hashtag paths query public Meta Ad Library records by keyword - not organic Facebook post keyword search.
    • Profile / page posts, post-by-id, and comments use the public profile/post helpers in the table.
    • Not exposed: organic keyword SERP, private/account-authenticated surfaces, messaging, publishing; Facebook trending omitted until a reliable public surface exists.

    First calls (one per platform)

    TikTok search

    bash
    curl --request POST 'https://api.desearch.ai/desearch/tiktok/search' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"query": "AI agents", "count": 10}'

    Instagram search

    bash
    curl --request POST 'https://api.desearch.ai/desearch/instagram/search' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"query": "desearch", "count": 10}'

    Facebook search (Ad Library keyword)

    bash
    curl --request POST 'https://api.desearch.ai/desearch/facebook/search' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"query": "running", "count": 10}'

    Body fields for all three search POSTs (OpenAPI): required query; optional count (1-100, default 10), cursor. TikTok also allows optional sort when supported.

    Pass TikTok post id values to GET /desearch/tiktok/comments/{video_id} when you need comments. Opaque upstream ids appear as providerId when present.

    Billing metadata

    Successful billable responses include headers:

    HeaderMeaning
    X-Desearch-Cost-UsdCost in USD for the request
    X-Desearch-Usage-CountBillable usage units
    X-Desearch-ServicePricing service key
    X-Desearch-CurrencyCurrency code

    JSON object bodies may also include cost_usd, usage_count, service, currency.
    JSON arrays expose billing via headers only.

    This page does not list public dollar rates - check Console / Pricing.

    Schemas

    Full request/response schemas: API Reference (TikTok Search, Instagram Search, Facebook Search, and each GET helper).

    Related