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
    A list of TikTok creators (or X, YouTube, LinkedIn people) who match a descriptionPeople Search (POST /desearch/people/search/tiktok)POST /desearch/tiktok/search, which returns posts

    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/{shortcode}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 (maximum number of items to return; accepted values 1 to 100, default 10). A response can contain fewer items than count. 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.

    Pagination and completeness

    Applies to search, profile posts, comments, and hashtag on TikTok, Instagram, and Facebook (12 endpoints).

    • Paging: Each of these endpoints returns a single page. The response is a JSON array. On these eleven endpoints, the response can include an x-desearch-next-cursor response header: POST /desearch/tiktok/search, POST /desearch/facebook/search, GET /desearch/instagram/profile/{username}/posts, GET /desearch/instagram/hashtag/{tag}, GET /desearch/instagram/comments/{shortcode}, GET /desearch/facebook/profile/{profile_id}/posts, GET /desearch/facebook/hashtag/{tag}, GET /desearch/facebook/comments/{post_id}, GET /desearch/tiktok/profile/{username}/posts, GET /desearch/tiktok/hashtag/{tag}, and GET /desearch/tiktok/comments/{video_id}. Send the header value back as cursor to get more results: in the JSON request body on the two search endpoints, and as a query parameter on the others. A forged cursor, or one from a different route or tag, returns 422. On the other endpoints, leave cursor unset.
    • Result count: count is the maximum number of items to return. Accepted values: 1 to 100. A response can contain fewer items than count, even when the platform shows more. On GET /desearch/facebook/comments/{post_id}, a response returns at most about 10 comments, whatever the count. Use the x-desearch-next-cursor header to get more results.
    • Totals: The response does not include a total. The number of items in the response is not the number of posts, comments, or media on the platform.
    • Fields that may be absent: On Instagram search results, followers and mediaCount are not returned for every item. Check for them before use.

    Fields marked as may be absent are not returned for every item. When a field is missing, treat the value as unknown, not zero. For a follower count of a specific Instagram account, use GET /desearch/instagram/profile/{username}. The profile response reports posts as postsCount; Instagram search results use a separate field, mediaCount.

    Instagram search example with one result that includes the optional fields and one that does not:

    json
    [ { "username": "example_one", "followers": 4483, "mediaCount": 210 }, { "username": "example_two" } ]

    In code, read optional fields defensively (item.get("followers") in Python, item.followers ?? null in JavaScript) and skip or mark items without them. Do not default them to 0.

    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