API StatusGitHubDiscordBlog

    Desearch API

    The Desearch API is a REST API for live search and data retrieval across web and social sources. It is designed for AI agents, search products, research tools, dashboards, and enrichment pipelines that need current information with clear usage and billing metadata.

    Base URL

    Use this canonical production base URL unless your Desearch team contact gives you an environment-specific URL:

    text
    https://api.desearch.ai

    All endpoint paths in the API Reference are relative to that base URL. For example:

    text
    POST https://api.desearch.ai/desearch/ai/search GET https://api.desearch.ai/web GET https://api.desearch.ai/twitter

    Core capabilities

    CapabilityDescription
    AI SearchSearch across selected sources and return links, summaries, or structured results for agent workflows.
    Web Search and CrawlRetrieve SERP-style results or crawl a target URL.
    X SearchSearch posts, retrieve posts/users, fetch replies, retweeters, user posts, and trends.
    TikTok APIsSearch TikTok and retrieve posts, profiles, profile posts, comments, hashtags, and trending posts.
    Facebook APIsSearch Facebook and retrieve posts, profiles/pages, page posts, comments, and hashtag posts.
    Instagram APIsSearch Instagram and retrieve media, profiles, profile posts, comments, and hashtag media.
    ForecastingCreate Numinous forecast jobs and retrieve forecast results.

    Authentication

    Every API request must include your API key in the Authorization header.

    http
    Authorization: $DESEARCH_API_KEY

    See Authorization and API Keys for secure key handling.

    First request

    bash
    curl --request POST 'https://api.desearch.ai/desearch/ai/search' \ --header 'Authorization: $DESEARCH_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "latest Bittensor subnet 22 updates", "tools": ["web", "twitter", "reddit"], "date_filter": "PAST_WEEK", "count": 10, "streaming": false }'

    Billing metadata

    Billable responses expose request-cost metadata in USD:

    • Response header: X-Desearch-Cost-Usd
    • Response body field for compatible JSON object responses: cost_usd
    • Additional metadata: X-Desearch-Usage-Count, X-Desearch-Service, X-Desearch-Currency, plus matching JSON fields when the response body is a JSON object.

    For arrays, text responses, and streaming/SSE, the body shape is preserved and billing metadata is available through headers. See Pricing and Billing.

    Common errors

    StatusMeaningWhat to check
    401UnauthorizedMissing, invalid, revoked, or wrong-environment API key.
    422Validation errorRequest body, query params, enum values, required fields, or old client examples.
    429Too many requestsAccount tier, rate limits, retry/backoff behavior, or usage spikes.
    500Server errorRetry later; if it persists, capture request ID/log details from Console.

    Next steps