{ "openapi": "3.1.0", "info": { "title": "Desearch API", "description": "The Desearch API provides live AI, web, and social search endpoints for agents, search products, research tools, dashboards, and data workflows. It supports AI Search, Web Search, X/Twitter retrieval, TikTok, Facebook, Instagram, crawl, and Numinous forecasting endpoints. Billable responses expose per-request cost metadata in USD.", "version": "1.0.0" }, "paths": { "/desearch/ai/search": { "post": { "tags": [ "AI Search" ], "summary": "AI Contextual Search", "description": "The Desearch API allows you to perform AI-powered web searches, gathering relevant information from multiple sources, including web pages, research papers, and social media discussions.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "desearch_desearch_ai_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScraperStreamingSynapseRequest" } } }, "required": true }, "responses": { "200": { "description": "A JSON object mapping tool names to their search results.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ResponseData" }, { "type": "object" }, { "type": "string" } ], "title": "Response Desearch Desearch Ai Search Post" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/ai/search/links/web": { "post": { "tags": [ "AI Search" ], "summary": "AI Web Search", "description": "This API allows users to search for links related to a given query (prompt) using multiple tools, excluding X (Twitter) Search. The API returns a list of relevant sources from selected platforms such as web pages, YouTube, Wikipedia, and ArXiv.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "search_links_web_desearch_ai_search_links_web_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinksSearchRequestWeb" } } }, "required": true }, "responses": { "200": { "description": "A JSON object mapping tool names to their search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchResponse" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently" }, "304": { "description": "Not Modified" } } } }, "/desearch/ai/search/links/twitter": { "post": { "tags": [ "AI Search" ], "summary": "AI X Posts Search", "description": "The X Posts Search API allows users to search for relevant links based on X search queries with leveraging AI-powered models. This API analyze links from X posts that match the given prompt. This API is useful for tracking trends, gathering insights, and retrieving real-time information from X.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "search_links_twitter_desearch_ai_search_links_twitter_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinksSearchRequestTwitter" } } }, "required": true }, "responses": { "200": { "description": "A JSON object mapping X Search to its search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XLinksSearchResponse" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/twitter": { "get": { "tags": [ "X Search" ], "summary": "X Search API", "description": "The X Search API enables users to retrieve relevant links and tweets based on specified search queries without utilizing AI-driven models. It analyzes links from X posts that align with the provided search criteria.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "twitter_search_twitter_get", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Advanced search query", "title": "Query" }, "description": "Advanced search query", "example": "Whats going on with Bittensor" }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(Top|Latest)$" }, { "type": "null" } ], "description": "Sort by Top or Latest", "default": "Top", "title": "Sort" }, "description": "Sort by Top or Latest", "example": "Top" }, { "name": "user", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User to search for", "title": "User" }, "description": "User to search for", "example": "elonmusk" }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start date in UTC (YYYY-MM-DD format)", "title": "Start Date" }, "description": "Start date in UTC (YYYY-MM-DD format)", "example": "2024-12-01" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End date in UTC (YYYY-MM-DD format)", "title": "End Date" }, "description": "End date in UTC (YYYY-MM-DD format)", "example": "2025-02-25" }, { "name": "lang", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Language code (e.g., en, es, fr)", "title": "Lang" }, "description": "Language code (e.g., en, es, fr)", "example": "en" }, { "name": "verified", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter for verified users", "title": "Verified" }, "description": "Filter for verified users", "example": true }, { "name": "blue_verified", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter for blue checkmark verified users", "title": "Blue Verified" }, "description": "Filter for blue checkmark verified users", "example": true }, { "name": "is_quote", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Include only tweets with quotes", "title": "Is Quote" }, "description": "Include only tweets with quotes", "example": true }, { "name": "is_video", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Include only tweets with videos", "title": "Is Video" }, "description": "Include only tweets with videos", "example": true }, { "name": "is_image", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Include only tweets with images", "title": "Is Image" }, "description": "Include only tweets with images", "example": true }, { "name": "min_retweets", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ], "description": "Minimum number of retweets", "title": "Min Retweets" }, "description": "Minimum number of retweets", "example": 1 }, { "name": "min_replies", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ], "description": "Minimum number of replies", "title": "Min Replies" }, "description": "Minimum number of replies", "example": 1 }, { "name": "min_likes", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ], "description": "Minimum number of likes", "title": "Min Likes" }, "description": "Minimum number of likes", "example": 1 }, { "name": "count", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 1 }, { "type": "null" } ], "description": "Number of tweets to retrieve", "default": 20, "title": "Count" }, "description": "Number of tweets to retrieve", "example": 10 } ], "responses": { "200": { "description": "A JSON object mapping X Search to its search results.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TwitterScraperTweet" } }, { "type": "object" } ], "title": "Response Twitter Search Twitter Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/twitter/urls": { "get": { "tags": [ "X Search" ], "summary": "Fetch Posts by URLs", "description": "Retrieve detailed information for multiple posts by providing their respective URLs. This endpoint extracts metadata, content, and relevant engagement metrics associated with each specified URL.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "twitter_by_urls_twitter_urls_get", "parameters": [ { "name": "urls", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "description": "List of urls that is to be retrieved.", "title": "Urls" }, "description": "List of urls that is to be retrieved.", "example": [ "https://x.com/RacingTriple/status/1892527552029499853" ] } ], "responses": { "200": { "description": "A JSON object mapping tweet URLs to their details.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TwitterScraperTweet" }, "title": "Response Twitter By Urls Twitter Urls Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/twitter/post": { "get": { "tags": [ "X Search" ], "summary": "Retrieve Post by ID", "description": "Retrieve comprehensive details of a post by specifying its unique ID. This endpoint provides metadata, content, and engagement metrics associated with the specified post.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "twitter_by_id_twitter_post_get", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "title": "Id" } } ], "responses": { "200": { "description": "A JSON object representing the post details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterScraperTweet" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/twitter/post/user": { "get": { "tags": [ "X Search" ], "summary": "Search X Posts by User", "description": "The X posts search by user API allows users to search for relevant links or tweets based on X search queries without leveraging AI-powered models. This API analyze links from X posts that match the given prompt.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tweets_by_user_twitter_post_user_get", "parameters": [ { "name": "user", "in": "query", "required": true, "schema": { "type": "string", "description": "User to search for", "title": "User" }, "description": "User to search for", "example": "elonmusk" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Advanced search query", "default": "", "title": "Query" }, "description": "Advanced search query", "example": "Whats going on with Bittensor" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of tweets to retrieve", "default": 10, "title": "Count" }, "description": "Number of tweets to retrieve", "example": 10 } ], "responses": { "200": { "description": "A JSON object mapping Twitter Search to its search results.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TwitterScraperTweet" } }, { "type": "object" } ], "title": "Response Tweets By User Twitter Post User Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/twitter/post/retweeters": { "get": { "tags": [ "X Search" ], "summary": "Get Retweeters of a Post", "description": "Retrieve the list of users who retweeted a specific post by its ID. Supports pagination via cursor.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "get_retweeters_twitter_post_retweeters_get", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the post to get retweeters for", "title": "Id" }, "description": "The ID of the post to get retweeters for", "example": "1982770537081532854" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination", "title": "Cursor" }, "description": "Cursor for pagination" } ], "responses": { "200": { "description": "A JSON object containing the list of users who retweeted the post.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XRetweetersResponse" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/twitter/user/posts": { "get": { "tags": [ "X Search" ], "summary": "Get X Posts by Username", "description": "Retrieve user's timeline posts by specifying their username. This endpoint fetches the latest tweets posted by the user associated with the provided username.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tweets_by_username_twitter_user_posts_get", "parameters": [ { "name": "username", "in": "query", "required": true, "schema": { "type": "string", "description": "Username to fetch posts for", "title": "Username" }, "description": "Username to fetch posts for", "example": "elonmusk" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination", "title": "Cursor" }, "description": "Cursor for pagination" } ], "responses": { "200": { "description": "A JSON object mapping X Posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XUserPostsResponse" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/twitter/replies": { "get": { "tags": [ "X Search" ], "summary": "Fetch User's Tweets and Replies", "description": "The tweets and replies by user API allows users to search for relevant links or tweets based on X search queries without leveraging AI-powered models. This API analyze links from X posts that match the given prompt.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tweets_replies_by_user_twitter_replies_get", "parameters": [ { "name": "user", "in": "query", "required": true, "schema": { "type": "string", "description": "The username of the user to search for.", "title": "User" }, "description": "The username of the user to search for.", "example": "elonmusk" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "The number of tweets to fetch.", "default": 10, "title": "Count" }, "description": "The number of tweets to fetch.", "example": 10 }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Advanced search query", "default": "", "title": "Query" }, "description": "Advanced search query", "example": "latest news on AI" } ], "responses": { "200": { "description": "A JSON object mapping Twitter Search to its search results.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TwitterScraperTweet" } }, { "type": "object" } ], "title": "Response Tweets Replies By User Twitter Replies Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/twitter/replies/post": { "get": { "tags": [ "X Search" ], "summary": "Retrieve Replies for a Post", "description": "The Tweets and Replies by User API enables users to retrieve relevant tweets and replies based on specified search queries without relying on AI-powered models. It analyzes and extracts links from X posts that align with the provided search criteria.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tweets_replies_by_post_twitter_replies_post_get", "parameters": [ { "name": "post_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the post to search for.", "title": "Post Id" }, "description": "The ID of the post to search for.", "example": "1234567890" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "The number of tweets to fetch.", "default": 10, "title": "Count" }, "description": "The number of tweets to fetch.", "example": 10 }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Advanced search query", "default": "", "title": "Query" }, "description": "Advanced search query", "example": "latest news on AI" } ], "responses": { "200": { "description": "A JSON object mapping Twitter Search to its search results.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TwitterScraperTweet" } }, { "type": "object" } ], "title": "Response Tweets Replies By Post Twitter Replies Post Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/twitter/trends": { "get": { "tags": [ "X Search" ], "summary": "Get X Trends", "description": "Retrieve trending topics on X for a given location using its WOEID (Where On Earth ID).\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "get_trends_twitter_trends_get", "parameters": [ { "name": "woeid", "in": "query", "required": true, "schema": { "type": "integer", "description": "The WOEID of the location (e.g. 23424977 for United States). WOEID List: https://gist.github.com/tedyblood/5bb5a9f78314cc1f478b3dd7cde790b9", "title": "Woeid" }, "description": "The WOEID of the location (e.g. 23424977 for United States). WOEID List: https://gist.github.com/tedyblood/5bb5a9f78314cc1f478b3dd7cde790b9", "example": 23424977 }, { "name": "count", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 30 }, { "type": "null" } ], "description": "The number of trends to return. Minimum is 30, maximum is 100.", "default": 30, "title": "Count" }, "description": "The number of trends to return. Minimum is 30, maximum is 100." } ], "responses": { "200": { "description": "A JSON object containing the list of trending topics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XTrendsResponse" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/tiktok/search": { "post": { "tags": [ "TikTok Search" ], "summary": "TikTok Search API", "description": "Search public TikTok posts by keyword using the public TikTok integration. Download/no-watermark media surfaces are intentionally not exposed.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tiktok_search_desearch_tiktok_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TikTokSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "A list of normalized TikTok posts.", "content": { "application/json": { "schema": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TikTokPost" }, "type": "array" }, { "type": "object" } ], "title": "Response Tiktok Search Desearch Tiktok Search Post" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/tiktok/post/{id}": { "get": { "tags": [ "TikTok Search" ], "summary": "Retrieve TikTok Post by ID", "description": "Retrieve normalized metadata for a public TikTok post by ID. This endpoint does not expose no-watermark/download-only media URLs.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tiktok_post_by_id_desearch_tiktok_post__id__get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "TikTok video/post ID", "title": "Id" }, "description": "TikTok video/post ID", "example": "7620891413932166433" } ], "responses": { "200": { "description": "A normalized TikTok post object.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TikTokPost" }, { "type": "object" } ], "title": "Response Tiktok Post By Id Desearch Tiktok Post Id Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/tiktok/profile/{username}": { "get": { "tags": [ "TikTok Search" ], "summary": "Retrieve TikTok Profile", "description": "Retrieve normalized public TikTok profile metadata by username.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tiktok_profile_desearch_tiktok_profile__username__get", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "description": "TikTok username without @", "title": "Username" }, "description": "TikTok username without @", "example": "tiktok" } ], "responses": { "200": { "description": "A normalized TikTok profile object.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TikTokProfile" }, { "type": "object" } ], "title": "Response Tiktok Profile Desearch Tiktok Profile Username Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/tiktok/profile/{username}/posts": { "get": { "tags": [ "TikTok Search" ], "summary": "Retrieve TikTok Profile Posts", "description": "Retrieve normalized public posts for a TikTok username.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tiktok_profile_posts_desearch_tiktok_profile__username__posts_get", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "description": "TikTok username without @", "title": "Username" }, "description": "TikTok username without @", "example": "tiktok" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of posts to retrieve", "default": 20, "title": "Count" }, "description": "Number of posts to retrieve" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" }, "description": "Pagination cursor" } ], "responses": { "200": { "description": "A list of normalized TikTok posts.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TikTokPost" } }, { "type": "object" } ], "title": "Response Tiktok Profile Posts Desearch Tiktok Profile Username Posts Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/tiktok/comments/{video_id}": { "get": { "tags": [ "TikTok Search" ], "summary": "Retrieve TikTok Comments", "description": "Retrieve normalized public comments for a TikTok video/post.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tiktok_comments_desearch_tiktok_comments__video_id__get", "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string", "description": "TikTok video/post ID", "title": "Video Id" }, "description": "TikTok video/post ID", "example": "7620891413932166433" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of comments to retrieve", "default": 20, "title": "Count" }, "description": "Number of comments to retrieve" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" }, "description": "Pagination cursor" } ], "responses": { "200": { "description": "A list of normalized TikTok comments.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TikTokComment" } }, { "type": "object" } ], "title": "Response Tiktok Comments Desearch Tiktok Comments Video Id Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/tiktok/hashtag/{tag}": { "get": { "tags": [ "TikTok Search" ], "summary": "Retrieve TikTok Hashtag Posts", "description": "Retrieve normalized public TikTok posts for a hashtag.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tiktok_hashtag_desearch_tiktok_hashtag__tag__get", "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string", "description": "Hashtag without #", "title": "Tag" }, "description": "Hashtag without #", "example": "bittensor" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of posts to retrieve", "default": 20, "title": "Count" }, "description": "Number of posts to retrieve" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" }, "description": "Pagination cursor" } ], "responses": { "200": { "description": "A list of normalized TikTok posts.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TikTokPost" } }, { "type": "object" } ], "title": "Response Tiktok Hashtag Desearch Tiktok Hashtag Tag Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/tiktok/trending": { "get": { "tags": [ "TikTok Search" ], "summary": "Retrieve TikTok Trending Posts", "description": "Retrieve normalized trending TikTok posts for a region where supported by the public TikTok integration.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "tiktok_trending_desearch_tiktok_trending_get", "parameters": [ { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Two-letter region code", "default": "US", "title": "Region" }, "description": "Two-letter region code", "example": "US" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of posts to retrieve", "default": 20, "title": "Count" }, "description": "Number of posts to retrieve" } ], "responses": { "200": { "description": "A list of normalized TikTok posts.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TikTokPost" } }, { "type": "object" } ], "title": "Response Tiktok Trending Desearch Tiktok Trending Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/facebook/search": { "post": { "tags": [ "Facebook Search" ], "summary": "Facebook Search API", "description": "Search public Meta Ad Library records by keyword. Organic Facebook post keyword search, private/account-authenticated surfaces, messaging, and publishing are intentionally not exposed.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "facebook_search_desearch_facebook_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "A list of normalized Facebook posts.", "content": { "application/json": { "schema": { "anyOf": [ { "items": { "$ref": "#/components/schemas/FacebookPost" }, "type": "array" }, { "type": "object" } ], "title": "Response Facebook Search Desearch Facebook Search Post" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/facebook/post/{id}": { "get": { "tags": [ "Facebook Search" ], "summary": "Retrieve Facebook Post by ID", "description": "Retrieve normalized metadata for a public Facebook post/media item by ID.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "facebook_post_by_id_desearch_facebook_post__id__get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Facebook public post/media ID", "title": "Id" }, "description": "Facebook public post/media ID", "example": "1525856912919657" } ], "responses": { "200": { "description": "A normalized Facebook post object.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/FacebookPost" }, { "type": "object" } ], "title": "Response Facebook Post By Id Desearch Facebook Post Id Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/facebook/profile/{profile_id}": { "get": { "tags": [ "Facebook Search" ], "summary": "Retrieve Facebook Profile or Page", "description": "Retrieve normalized public Facebook profile/page metadata by username, vanity handle, or public ID.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "facebook_profile_desearch_facebook_profile__profile_id__get", "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Facebook profile/page ID or public handle", "title": "Profile Id" }, "description": "Facebook profile/page ID or public handle", "example": "facebook" } ], "responses": { "200": { "description": "A normalized Facebook profile/page object.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/FacebookProfile" }, { "type": "object" } ], "title": "Response Facebook Profile Desearch Facebook Profile Profile Id Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/facebook/profile/{profile_id}/posts": { "get": { "tags": [ "Facebook Search" ], "summary": "Retrieve Facebook Profile/Page Posts", "description": "Retrieve normalized public posts for a Facebook profile/page.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "facebook_profile_posts_desearch_facebook_profile__profile_id__posts_get", "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Facebook profile/page ID or public handle", "title": "Profile Id" }, "description": "Facebook profile/page ID or public handle", "example": "facebook" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of posts to retrieve", "default": 20, "title": "Count" }, "description": "Number of posts to retrieve" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" }, "description": "Pagination cursor" } ], "responses": { "200": { "description": "A list of normalized Facebook posts.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/FacebookPost" } }, { "type": "object" } ], "title": "Response Facebook Profile Posts Desearch Facebook Profile Profile Id Posts Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/facebook/comments/{post_id}": { "get": { "tags": [ "Facebook Search" ], "summary": "Retrieve Facebook Comments", "description": "Retrieve normalized public comments for a Facebook post/media item.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "facebook_comments_desearch_facebook_comments__post_id__get", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Facebook public post/media ID", "title": "Post Id" }, "description": "Facebook public post/media ID", "example": "1525856912919657" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of comments to retrieve", "default": 20, "title": "Count" }, "description": "Number of comments to retrieve" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" }, "description": "Pagination cursor" } ], "responses": { "200": { "description": "A list of normalized Facebook comments.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/FacebookComment" } }, { "type": "object" } ], "title": "Response Facebook Comments Desearch Facebook Comments Post Id Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/facebook/hashtag/{tag}": { "get": { "tags": [ "Facebook Search" ], "summary": "Retrieve Facebook Hashtag Posts", "description": "Retrieve normalized public Meta Ad Library records for a keyword/hashtag. Organic Facebook hashtag search and Facebook trending are intentionally omitted until a reliable public surface exists.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "facebook_hashtag_desearch_facebook_hashtag__tag__get", "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string", "description": "Hashtag without #", "title": "Tag" }, "description": "Hashtag without #", "example": "bittensor" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of posts to retrieve", "default": 20, "title": "Count" }, "description": "Number of posts to retrieve" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" }, "description": "Pagination cursor" } ], "responses": { "200": { "description": "A list of normalized Facebook posts.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/FacebookPost" } }, { "type": "object" } ], "title": "Response Facebook Hashtag Desearch Facebook Hashtag Tag Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/instagram/search": { "post": { "tags": [ "Instagram Search" ], "summary": "Instagram Search API", "description": "Search public Instagram profiles by keyword. Hashtag/media discovery remains available through /desearch/instagram/hashtag/{tag}. Private, login, posting, messaging, and download-only surfaces are intentionally not exposed.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "instagram_search_desearch_instagram_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstagramSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "A list of normalized Instagram search results.", "content": { "application/json": { "schema": { "anyOf": [ { "items": { "$ref": "#/components/schemas/InstagramSearchResult" }, "type": "array" }, { "type": "object" } ], "title": "Response Instagram Search Desearch Instagram Search Post" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/instagram/media/{id}": { "get": { "tags": [ "Instagram Search" ], "summary": "Retrieve Instagram Media by ID", "description": "Retrieve normalized metadata for a public Instagram media/post by shortcode, ID, or URL.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "instagram_media_desearch_instagram_media__id__get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Instagram media shortcode, ID, or public URL", "title": "Id" }, "description": "Instagram media shortcode, ID, or public URL", "example": "DY79rTVS6OK" } ], "responses": { "200": { "description": "A normalized Instagram media object.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InstagramMedia" }, { "type": "object" } ], "title": "Response Instagram Media Desearch Instagram Media Id Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/instagram/profile/{username}": { "get": { "tags": [ "Instagram Search" ], "summary": "Retrieve Instagram Profile", "description": "Retrieve normalized public Instagram profile metadata by username.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "instagram_profile_desearch_instagram_profile__username__get", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "description": "Instagram username without @", "title": "Username" }, "description": "Instagram username without @", "example": "instagram" } ], "responses": { "200": { "description": "A normalized Instagram profile object.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InstagramProfile" }, { "type": "object" } ], "title": "Response Instagram Profile Desearch Instagram Profile Username Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/instagram/profile/{username}/posts": { "get": { "tags": [ "Instagram Search" ], "summary": "Retrieve Instagram Profile Posts", "description": "Retrieve normalized public posts for an Instagram username.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "instagram_profile_posts_desearch_instagram_profile__username__posts_get", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "description": "Instagram username without @", "title": "Username" }, "description": "Instagram username without @", "example": "instagram" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of posts to retrieve", "default": 20, "title": "Count" }, "description": "Number of posts to retrieve" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" }, "description": "Pagination cursor" } ], "responses": { "200": { "description": "A list of normalized Instagram media objects.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/InstagramMedia" } }, { "type": "object" } ], "title": "Response Instagram Profile Posts Desearch Instagram Profile Username Posts Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/instagram/comments/{media_id}": { "get": { "tags": [ "Instagram Search" ], "summary": "Retrieve Instagram Comments", "description": "Retrieve normalized public comments for an Instagram media/post.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "instagram_comments_desearch_instagram_comments__media_id__get", "parameters": [ { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Instagram media shortcode, ID, or public URL", "title": "Media Id" }, "description": "Instagram media shortcode, ID, or public URL", "example": "DY79rTVS6OK" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of comments to retrieve", "default": 20, "title": "Count" }, "description": "Number of comments to retrieve" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" }, "description": "Pagination cursor" } ], "responses": { "200": { "description": "A list of normalized Instagram comments.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/InstagramComment" } }, { "type": "object" } ], "title": "Response Instagram Comments Desearch Instagram Comments Media Id Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/desearch/instagram/hashtag/{tag}": { "get": { "tags": [ "Instagram Search" ], "summary": "Retrieve Instagram Hashtag Media", "description": "Retrieve normalized public Instagram media for a hashtag. Instagram trending is not exposed until a stable unauthenticated public surface is selected.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "instagram_hashtag_desearch_instagram_hashtag__tag__get", "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string", "description": "Hashtag without #", "title": "Tag" }, "description": "Hashtag without #", "example": "bittensor" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of media objects to retrieve", "default": 20, "title": "Count" }, "description": "Number of media objects to retrieve" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" }, "description": "Pagination cursor" } ], "responses": { "200": { "description": "A list of normalized Instagram media objects.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/InstagramMedia" } }, { "type": "object" } ], "title": "Response Instagram Hashtag Desearch Instagram Hashtag Tag Get" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/web": { "get": { "tags": [ "Web Search" ], "summary": "SERP Web Search API", "description": "This API allows users to search for any information over the web. This replicates a typical search engine experience, where users can search for any information they need.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "web_search_web_get", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "The search query string, e.g., 'latest news on AI'.", "title": "Query" }, "description": "The search query string, e.g., 'latest news on AI'.", "example": "latest news on AI" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "description": "How many results to skip. It's used for pagination. (e.g., 0 (default) is the first page of results, 10 is the 2nd page of results, 20 is the 3rd page of results, etc.).", "default": 0, "title": "Start" }, "description": "How many results to skip. It's used for pagination. (e.g., 0 (default) is the first page of results, 10 is the 2nd page of results, 20 is the 3rd page of results, etc.).", "example": 10 } ], "responses": { "201": { "description": "A JSON object mapping Web Search to its search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchResultsResponse" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/web/crawl": { "get": { "tags": [ "Web Search" ], "summary": "Crawl API", "description": "The Desearch API allows you to crawl web content\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "desearch_crawl_web_crawl_get", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "description": "Url to crawl", "title": "Url" }, "description": "Url to crawl", "example": "https://en.wikipedia.org/wiki/Artificial_intelligence" }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "html", "text" ], "type": "string", "description": "Format of the content to be returned. Options are 'html' or 'text'. Default is 'html'.", "default": "text", "title": "Format" }, "description": "Format of the content to be returned. Options are 'html' or 'text'. Default is 'html'.", "example": "html" }, { "name": "js", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string", "description": "Render the page with a headless browser before extracting content. Use for SPAs or pages whose body is populated by JavaScript. Must be exactly `true` or `false` (case-sensitive); enables a separate billing tier when set to `true`.", "default": "false", "title": "Js" }, "description": "Render the page with a headless browser before extracting content. Use for SPAs or pages whose body is populated by JavaScript. Must be exactly `true` or `false` (case-sensitive); enables a separate billing tier when set to `true`." }, { "name": "wait", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 30000, "minimum": 0 }, { "type": "null" } ], "description": "Optional extra wait in milliseconds after the page loads. Only applied when ``js=true``.", "title": "Wait" }, "description": "Optional extra wait in milliseconds after the page loads. Only applied when ``js=true``." } ], "responses": { "200": { "description": "Content of the web link", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "502": { "description": "Crawler upstream unavailable" }, "301": { "description": "Moved Permanently", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/MovedPermanentlyResponse" } } } }, "304": { "description": "Not Modified" } } } }, "/numinous/forecasts": { "post": { "tags": [ "Numinous Forecasting" ], "summary": "Create Forecast Job", "description": "Submit a forecasting question to the Numinous AI superforecasting system powered by Bittensor Subnet 6. Returns a prediction job ID to poll for results. Supports two modes: **structured** (title + description + cutoff) for precise results, or **query** (natural language question) for quick exploration.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "create_forecast_numinous_forecasts_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NuminousForecastRequest" } } }, "required": true }, "responses": { "202": { "description": "A prediction job ID and initial PENDING status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NuminousJobCreatedResponse" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } } } }, "/numinous/forecasts/{prediction_id}": { "get": { "tags": [ "Numinous Forecasting" ], "summary": "Get Forecast Result", "description": "Poll the status of a prediction job created via POST /numinous/forecasts. Poll every 5 seconds — jobs typically complete within 30–120 seconds. The `prediction_id` UUID acts as an access token; no API key is required for polling.\n\nBilling metadata: successful billable responses include the `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, and `X-Desearch-Currency` headers. JSON object responses also include optional `cost_usd`, `usage_count`, `service`, and `currency` fields. For example, `usage_count=10` at `$0.015 / 1,000` resolves to `cost_usd=0.00015`. JSON arrays, text, and streaming responses keep their body shape and expose billing metadata only through headers.", "operationId": "get_forecast_numinous_forecasts__prediction_id__get", "parameters": [ { "name": "prediction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Prediction Id" } } ], "responses": { "200": { "description": "Current job status and result when completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NuminousJobStatusResponse" } } }, "headers": { "X-Desearch-Cost-Usd": { "description": "Billable request cost in US dollars.", "schema": { "type": "number", "format": "float", "example": 0.00015 } }, "X-Desearch-Usage-Count": { "description": "Billable usage units applied to this request.", "schema": { "type": "integer", "example": 10 } }, "X-Desearch-Service": { "description": "Pricing service or endpoint used to calculate the request cost.", "schema": { "type": "string", "example": "/twitter" } }, "X-Desearch-Currency": { "description": "Currency for cost metadata. Currently always USD.", "schema": { "type": "string", "example": "USD" } } } }, "404": { "description": "Prediction job not found" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ChatHistoryItem": { "properties": { "prompt": { "type": "string", "title": "Prompt" }, "completion": { "type": "string", "title": "Completion", "default": "" } }, "type": "object", "required": [ "prompt" ], "title": "ChatHistoryItem" }, "DateFilterEnum": { "type": "string", "enum": [ "PAST_24_HOURS", "PAST_2_DAYS", "PAST_WEEK", "PAST_2_WEEKS", "PAST_MONTH", "PAST_2_MONTHS", "PAST_YEAR", "PAST_2_YEARS" ], "title": "DateFilterEnum" }, "FacebookComment": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "comment-123" }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postid", "example": "1525856912919657" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "example": "Comment text" }, "createTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createtime", "example": "2026-05-01T10:30:00Z" }, "author": { "anyOf": [ { "$ref": "#/components/schemas/FacebookProfile" }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Likes", "example": 42 }, "replies": { "items": { "type": "object" }, "type": "array", "title": "Replies" } }, "type": "object", "title": "FacebookComment" }, "FacebookMedia": { "properties": { "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "example": "photo" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "example": "https://example.com/photo.jpg" }, "thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thumbnail", "example": "https://example.com/thumb.jpg" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width", "example": 1200 }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height", "example": 630 } }, "type": "object", "title": "FacebookMedia" }, "FacebookPost": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "1525856912919657" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "example": "https://www.facebook.com/facebook/posts/1525856912919657" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "example": "Post text" }, "createTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createtime", "example": "2026-05-01T10:00:00Z" }, "author": { "anyOf": [ { "$ref": "#/components/schemas/FacebookProfile" }, { "type": "null" } ] }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/FacebookPostStats" }, { "type": "null" } ] }, "media": { "items": { "$ref": "#/components/schemas/FacebookMedia" }, "type": "array", "title": "Media" }, "hashtags": { "items": { "type": "string" }, "type": "array", "title": "Hashtags" } }, "type": "object", "title": "FacebookPost" }, "FacebookPostStats": { "properties": { "reactionCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Reactioncount", "example": 1200 }, "commentCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Commentcount", "example": 80 }, "shareCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sharecount", "example": 24 }, "viewCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Viewcount", "example": 10000 } }, "type": "object", "title": "FacebookPostStats" }, "FacebookProfile": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "123456789" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Username", "example": "facebook" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "example": "Desearch AI" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "example": "https://www.facebook.com/facebook" }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "example": "https://example.com/avatar.jpg" }, "verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Verified", "example": true }, "bio": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bio", "example": "Public search API" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "example": "Software" }, "followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Followers", "example": 50000 }, "likes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Likes", "example": 12000 } }, "type": "object", "title": "FacebookProfile" }, "FacebookSearchRequest": { "properties": { "query": { "type": "string", "title": "Query", "description": "Meta Ad Library keyword, phrase, or hashtag to search", "example": "running" }, "count": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Count", "description": "Number of results to return", "default": 10 }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor", "description": "Pagination cursor" } }, "type": "object", "required": [ "query" ], "title": "FacebookSearchRequest" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InstagramComment": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "1789123456789" }, "mediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mediaid", "example": "DY79rTVS6OK" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "example": "comment text" }, "createTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createtime", "example": "2024-01-15T11:00:00Z" }, "author": { "anyOf": [ { "$ref": "#/components/schemas/InstagramProfile" }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Likes", "example": 42 }, "replies": { "items": { "type": "object" }, "type": "array", "title": "Replies" } }, "type": "object", "title": "InstagramComment" }, "InstagramMedia": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "3234567890123456789" }, "shortcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Shortcode", "example": "DY79rTVS6OK" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "example": "https://www.instagram.com/p/DY79rTVS6OK/" }, "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Caption", "example": "caption text" }, "createTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createtime", "example": "2024-01-15T10:30:00Z" }, "mediaType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mediatype", "example": "image" }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mediaurl", "example": "https://example.com/media.jpg" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thumbnailurl", "example": "https://example.com/thumb.jpg" }, "author": { "anyOf": [ { "$ref": "#/components/schemas/InstagramProfile" }, { "type": "null" } ] }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/InstagramStats" }, { "type": "null" } ] }, "hashtags": { "items": { "type": "string" }, "type": "array", "title": "Hashtags" }, "mentions": { "items": { "type": "string" }, "type": "array", "title": "Mentions" }, "children": { "items": { "type": "object" }, "type": "array", "title": "Children" } }, "type": "object", "title": "InstagramMedia" }, "InstagramProfile": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "12345" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Username", "example": "instagram" }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fullname", "example": "Desearch" }, "biography": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Biography", "example": "Search AI" }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "example": "https://example.com/avatar.jpg" }, "verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Verified", "example": true }, "private": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Private", "example": false }, "followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Followers", "example": 50000 }, "following": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Following", "example": 1200 }, "postsCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Postscount", "example": 250 }, "externalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Externalurl", "example": "https://desearch.ai" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "example": "Software" } }, "type": "object", "title": "InstagramProfile" }, "InstagramSearchRequest": { "properties": { "query": { "type": "string", "title": "Query", "description": "Keyword, username, or phrase to search on Instagram", "example": "desearch" }, "count": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Count", "description": "Number of results to return", "default": 10 }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor", "description": "Pagination cursor" } }, "type": "object", "required": [ "query" ], "title": "InstagramSearchRequest" }, "InstagramSearchResult": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "12345" }, "type": { "type": "string", "enum": [ "profile", "hashtag", "media" ], "title": "Type", "example": "profile" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Username", "example": "instagram" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "example": "Desearch" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "example": "https://www.instagram.com/instagram/" }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "example": "https://example.com/avatar.jpg" }, "followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Followers", "example": 50000 }, "mediaCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Mediacount", "example": 250 } }, "type": "object", "required": [ "type" ], "title": "InstagramSearchResult" }, "InstagramStats": { "properties": { "likeCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Likecount", "example": 5000 }, "commentCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Commentcount", "example": 120 }, "viewCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Viewcount", "example": 120000 }, "playCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Playcount", "example": 120000 } }, "type": "object", "title": "InstagramStats" }, "InternalServerErrorResponse": { "properties": { "detail": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "object", "title": "Detail", "example": { "description": "An unexpected error occurred on the server.", "error_code": 500, "message": "Internal Server Error" } } }, "type": "object", "required": [ "detail" ], "title": "InternalServerErrorResponse" }, "LinksSearchRequestTwitter": { "properties": { "prompt": { "type": "string", "title": "Prompt", "description": "Search query prompt", "example": "What are the recent sport events?" }, "count": { "anyOf": [ { "type": "integer", "maximum": 200.0, "minimum": 10.0 }, { "type": "null" } ], "title": "Count", "description": "The number of results to return per source. Min 10. Max 200.", "default": 10 } }, "type": "object", "required": [ "prompt" ], "title": "LinksSearchRequestTwitter" }, "LinksSearchRequestWeb": { "properties": { "prompt": { "type": "string", "title": "Prompt", "description": "Search query prompt", "example": "What are the recent sport events?" }, "tools": { "items": { "anyOf": [ { "$ref": "#/components/schemas/WebToolEnum" }, { "type": "string" } ] }, "type": "array", "title": "Tools", "description": "List of tools to search with", "example": [ "web", "hackernews", "reddit", "wikipedia", "youtube", "arxiv" ] }, "count": { "anyOf": [ { "type": "integer", "maximum": 200.0, "minimum": 10.0 }, { "type": "null" } ], "title": "Count", "description": "The number of results to return per source. Min 10. Max 200.", "default": 10 } }, "type": "object", "required": [ "prompt", "tools" ], "title": "LinksSearchRequestWeb" }, "MediaSize": { "properties": { "w": { "type": "integer", "title": "W", "example": 1200 }, "h": { "type": "integer", "title": "H", "example": 675 }, "resize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resize", "example": "fit" } }, "type": "object", "required": [ "w", "h" ], "title": "MediaSize" }, "MovedPermanentlyResponse": { "properties": { "detail": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "object", "title": "Detail", "example": { "error_code": 301, "location": "https://new-url.com", "message": "Moved Permanently" } } }, "type": "object", "required": [ "detail" ], "title": "MovedPermanentlyResponse" }, "NuminousForecastRequest": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "cutoff": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cutoff" }, "topics": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Topics" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query" }, "agent_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Version Id" } }, "type": "object", "title": "NuminousForecastRequest" }, "NuminousForecastResult": { "properties": { "prediction": { "type": "number", "title": "Prediction", "description": "Probability estimate in [0.0, 1.0]. E.g. 0.72 means 72% probability of YES.", "example": 0.72 }, "forecaster_name": { "type": "string", "title": "Forecaster Name", "description": "Identifier of the forecaster that produced the result.", "example": "pool_based_miner_forecaster" }, "forecasted_at": { "type": "string", "title": "Forecasted At", "description": "ISO 8601 datetime when the forecast was generated.", "example": "2026-02-17T18:00:45Z" }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/NuminousForecasterMetadata" }, { "type": "null" } ], "description": "Forecaster metadata including miner info and optional reasoning." }, "parsed_fields": { "anyOf": [ { "$ref": "#/components/schemas/NuminousParsedFields" }, { "type": "null" } ], "description": "Fields extracted from the natural language query. Present only in query mode." } }, "type": "object", "required": [ "prediction", "forecaster_name", "forecasted_at" ], "title": "NuminousForecastResult" }, "NuminousForecasterMetadata": { "properties": { "miner_uid": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Miner Uid", "description": "Miner UID on the Bittensor subnet." }, "miner_hotkey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Miner Hotkey", "description": "Miner hotkey (SS58 address)." }, "pool": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pool", "description": "Scoring pool used (e.g. GLOBAL_BRIER)." }, "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version Id", "description": "Agent version UUID." }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name", "description": "Agent name." }, "version_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version Number", "description": "Agent version number." }, "raw_prediction": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Raw Prediction", "description": "Raw probability from the miner." }, "event_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Title", "description": "Event title used for the forecast." }, "event_cutoff": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Cutoff", "description": "ISO 8601 cutoff datetime for the event." }, "reasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning", "description": "Optional reasoning from the forecaster." } }, "type": "object", "title": "NuminousForecasterMetadata" }, "NuminousJobCreatedResponse": { "properties": { "prediction_id": { "type": "string", "format": "uuid", "title": "Prediction Id", "description": "Unique identifier for the prediction job. Use this to poll for results.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "$ref": "#/components/schemas/NuminousJobStatus", "description": "Initial job status. Always PENDING on creation.", "example": "PENDING" } }, "type": "object", "required": [ "prediction_id", "status" ], "title": "NuminousJobCreatedResponse" }, "NuminousJobStatus": { "type": "string", "enum": [ "PENDING", "RUNNING", "COMPLETED", "FAILED" ], "title": "NuminousJobStatus" }, "NuminousJobStatusResponse": { "properties": { "prediction_id": { "type": "string", "format": "uuid", "title": "Prediction Id", "description": "Job identifier.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "$ref": "#/components/schemas/NuminousJobStatus", "description": "Current job status: PENDING, RUNNING, COMPLETED, or FAILED.", "example": "COMPLETED" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "ISO 8601 datetime when the job was created.", "example": "2026-02-17T18:00:00Z" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/NuminousForecastResult" }, { "type": "null" } ], "description": "Forecast result. Present when status is COMPLETED." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error description. Present when status is FAILED." } }, "type": "object", "required": [ "prediction_id", "status" ], "title": "NuminousJobStatusResponse" }, "NuminousParsedFields": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Extracted event title." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Extracted resolution criteria." }, "cutoff": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cutoff", "description": "Extracted ISO 8601 cutoff datetime." }, "topics": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Topics", "description": "Extracted topic categories." } }, "type": "object", "title": "NuminousParsedFields" }, "Rect": { "properties": { "x": { "type": "integer", "title": "X", "example": 100 }, "y": { "type": "integer", "title": "Y", "example": 100 }, "w": { "type": "integer", "title": "W", "example": 200 }, "h": { "type": "integer", "title": "H", "example": 200 } }, "type": "object", "required": [ "x", "y", "w", "h" ], "title": "Rect" }, "ResponseData": { "properties": { "hacker_news_search": { "anyOf": [ { "items": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Hacker News Search", "description": "Search results from Hacker News, listing articles and discussions relevant to the query.", "example": [ { "link": "https://news.ycombinator.com/item?id=35114983", "snippet": "Mar 12, 2023 � As a decentralized AI network, Bittensor leverages the power of AI to drive innovation and collaboration on a global scale.", "title": "How Bittensor Is Pioneering a New Era of AI Innovation - Hacker News" } ] }, "reddit_search": { "anyOf": [ { "items": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Reddit Search", "description": "Search results from Reddit, providing discussions and posts related to the search query.", "example": [ { "link": "https://www.reddit.com/r/bittensor_/comments/1blm5iv/thinking_of_going_in_big_on_bittensor/", "snippet": "Mar 23, 2024 � I have great hopes for Bittensor and am about to commit to a sizeable position to which I will probably be adding over the coming months and even years.", "title": "Thinking of going in big on Bittensor : r/bittensor_ - Reddit" } ] }, "search": { "anyOf": [ { "items": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Search", "description": "General search results related to the query.", "example": [ { "link": "https://www.thebigwhale.io/tokens/bittensor", "snippet": "Bittensor (TAO) is a decentralized, open-source, and permissionless machine learning network that transforms machine intelligence into a tradable commodity.", "title": "What is Bittensor?" } ] }, "youtube_search": { "anyOf": [ { "items": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Youtube Search", "description": "Search results from YouTube, including relevant videos matching the search criteria.", "example": [ { "link": "https://www.youtube.com/watch?v=tDWhnsZB6XI", "snippet": "In this video, I break down exactly how I'm maximizing my $TAO stack through smart staking strategies on the Bittensor network ...", "title": "TAO (Bittensor) is PUMPING - how to make more profit with Staking 💰" } ] }, "tweets": { "anyOf": [ { "items": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Tweets", "description": "Tweets related to the search query.", "example": [ { "bookmark_count": 2, "conversation_id": "1932946234920349827", "created_at": "2025-06-11T23:41:09.000Z", "display_text_range": [ 0, 269 ], "entities": { "hashtags": [], "media": [ { "display_url": "pic.x.com/L1icjTabYS", "expanded_url": "https://x.com/HOSS_ibc/status/1932946234920349827/photo/1", "ext_media_availability": { "status": "Available" }, "features": { "large": { "faces": [ { "h": 77, "w": 77, "x": 1877, "y": 521 }, { "h": 93, "w": 93, "x": 971, "y": 571 } ] }, "medium": { "faces": [ { "h": 45, "w": 45, "x": 1100, "y": 305 }, { "h": 55, "w": 55, "x": 569, "y": 335 } ] }, "orig": { "faces": [ { "h": 137, "w": 137, "x": 3301, "y": 917 }, { "h": 165, "w": 165, "x": 1708, "y": 1005 } ] }, "small": { "faces": [ { "h": 25, "w": 25, "x": 623, "y": 173 }, { "h": 31, "w": 31, "x": 322, "y": 189 } ] } }, "id_str": "1932944082281574400", "indices": [ 270, 293 ], "media_key": "3_1932944082281574400", "media_url_https": "https://pbs.twimg.com/media/GtMyZtMWMAAPfq9.jpg", "original_info": { "focus_rects": [ { "h": 1800, "w": 3214, "x": 0, "y": 0 }, { "h": 1800, "w": 1800, "x": 0, "y": 0 }, { "h": 1800, "w": 1579, "x": 0, "y": 0 }, { "h": 1800, "w": 900, "x": 0, "y": 0 }, { "h": 1800, "w": 3600, "x": 0, "y": 0 } ], "height": 1800, "width": 3600 }, "sizes": { "large": { "h": 1024, "resize": "fit", "w": 2048 }, "medium": { "h": 600, "resize": "fit", "w": 1200 }, "small": { "h": 340, "resize": "fit", "w": 680 }, "thumb": { "h": 150, "resize": "crop", "w": 150 } }, "type": "photo", "url": "https://t.co/L1icjTabYS" } ], "symbols": [ { "indices": [ 10, 14 ], "text": "TAO" } ], "timestamps": [], "urls": [], "user_mentions": [] }, "extended_entities": { "media": [ { "display_url": "pic.x.com/L1icjTabYS", "expanded_url": "https://x.com/HOSS_ibc/status/1932946234920349827/photo/1", "ext_media_availability": { "status": "Available" }, "features": { "large": { "faces": [ { "h": 77, "w": 77, "x": 1877, "y": 521 }, { "h": 93, "w": 93, "x": 971, "y": 571 } ] }, "medium": { "faces": [ { "h": 45, "w": 45, "x": 1100, "y": 305 }, { "h": 55, "w": 55, "x": 569, "y": 335 } ] }, "orig": { "faces": [ { "h": 137, "w": 137, "x": 3301, "y": 917 }, { "h": 165, "w": 165, "x": 1708, "y": 1005 } ] }, "small": { "faces": [ { "h": 25, "w": 25, "x": 623, "y": 173 }, { "h": 31, "w": 31, "x": 322, "y": 189 } ] } }, "id_str": "1932944082281574400", "indices": [ 270, 293 ], "media_key": "3_1932944082281574400", "media_url_https": "https://pbs.twimg.com/media/GtMyZtMWMAAPfq9.jpg", "original_info": { "focus_rects": [ { "h": 1800, "w": 3214, "x": 0, "y": 0 }, { "h": 1800, "w": 1800, "x": 0, "y": 0 }, { "h": 1800, "w": 1579, "x": 0, "y": 0 }, { "h": 1800, "w": 900, "x": 0, "y": 0 }, { "h": 1800, "w": 3600, "x": 0, "y": 0 } ], "height": 1800, "width": 3600 }, "sizes": { "large": { "h": 1024, "resize": "fit", "w": 2048 }, "medium": { "h": 600, "resize": "fit", "w": 1200 }, "small": { "h": 340, "resize": "fit", "w": 680 }, "thumb": { "h": 150, "resize": "crop", "w": 150 } }, "type": "photo", "url": "https://t.co/L1icjTabYS" } ] }, "id": "1932946234920349827", "is_quote_tweet": false, "is_retweet": false, "lang": "en", "like_count": 31, "media": [ { "media_url": "https://pbs.twimg.com/media/GtMyZtMWMAAPfq9.jpg", "type": "photo" } ], "quote_count": 3, "reply_count": 16, "retweet_count": 3, "text": "Bittensor $TAO seems oversold here.\n\nGrowth up but price is down\n\nPrice Valuation (Next 12 Months)\n\nFactors \n\nTechnical: Trading above 200-day MA; support at $350-$380. \n\nFundamental: Halving, subnet growth, institutional interest (e.g., Grayscale’s Bittensor Trust). \n\nSentiment: Strong staking (72%) and developer activity.\n\nForecast (Jun 2025-Jun 2026) \n\nConservative: $350-$600 \n\nBase: $600-$900 \n\nBullish: $900-$1,200", "url": "https://x.com/HOSS_ibc/status/1932946234920349827", "user": { "can_dm": true, "can_media_tag": false, "created_at": "Sun Jul 18 05:20:07 +0000 2021", "description": "Entrepreneur, Angel Investor & Product Advisor | 4+ years full-time in Crypto | 16+ years building businesses | Passionate about DeFi, Art & impactful content", "entities": { "description": { "urls": [] }, "url": { "urls": [ { "display_url": "metimmerse.io/hoss", "expanded_url": "https://metimmerse.io/hoss", "indices": [ 0, 23 ], "url": "https://t.co/kAQCAPyc7F" } ] } }, "favourites_count": 163851, "followers_count": 63156, "id": "1416628772565143561", "is_blue_verified": true, "listed_count": 460, "location": "Tweets aren't financial advice", "media_count": 8421, "name": "Hoss", "pinned_tweet_ids": [ "1932920070222889063" ], "profile_banner_url": "https://pbs.twimg.com/profile_banners/1416628772565143561/1749700252", "profile_image_url": "https://pbs.twimg.com/profile_images/1915178001026723840/s0MX6RPL_normal.jpg", "statuses_count": 77157, "url": "https://x.com/HOSS_ibc", "username": "HOSS_ibc", "verified": false } } ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Additional text related to the search query.", "example": "This is some additional text related to the search query." }, "miner_link_scores": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Miner Link Scores", "description": "A list of miner link scores, typically used in AI-generated content results.", "example": { "https://news.ycombinator.com/item?id=35114983": "MEDIUM", "https://news.ycombinator.com/item?id=42684057": "MEDIUM" } }, "completion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completion", "description": "Generated completion text or response, typically used in AI-generated content results.", "example": "Bittensor is a decentralized, open-source machine learning network that transforms AI models into tradable commodities." } }, "type": "object", "title": "ResponseData" }, "ResultTypeEnum": { "type": "string", "enum": [ "ONLY_LINKS", "LINKS_WITH_FINAL_SUMMARY" ], "title": "ResultTypeEnum" }, "ScraperStreamingSynapseRequest": { "properties": { "prompt": { "type": "string", "title": "Prompt", "description": "Search query prompt", "example": "Bittensor" }, "tools": { "items": { "anyOf": [ { "$ref": "#/components/schemas/ToolEnum" }, { "type": "string" } ] }, "type": "array", "title": "Tools", "description": "A list of tools to be used for the search", "example": [ "web", "hackernews", "reddit", "wikipedia", "youtube", "twitter", "arxiv" ] }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date", "description": "The start date for the search query. Format: YYYY-MM-DDTHH:MM:SSZ (UTC)", "examples": [ "2025-05-01T00:00:00Z" ] }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date", "description": "The end date for the search query. Format: YYYY-MM-DDTHH:MM:SSZ (UTC)", "examples": [ "2025-05-03T00:00:00Z" ] }, "date_filter": { "anyOf": [ { "$ref": "#/components/schemas/DateFilterEnum" }, { "type": "null" } ], "description": "Predefined date filters for the search results, or you can use specific start and end dates", "default": "PAST_24_HOURS", "example": "PAST_24_HOURS" }, "streaming": { "type": "boolean", "title": "Streaming", "description": "Whether to stream results", "default": true, "example": true }, "result_type": { "anyOf": [ { "$ref": "#/components/schemas/ResultTypeEnum" }, { "type": "null" } ], "description": "The result type to be used for the search", "default": "LINKS_WITH_FINAL_SUMMARY", "example": "LINKS_WITH_FINAL_SUMMARY" }, "system_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Message", "description": "The system message to be used for the search", "default": "", "example": "Summarize the content by categorizing key points into 'Pros' and 'Cons' sections." }, "scoring_system_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scoring System Message", "description": "System message for scoring the response", "example": "Business Relevance Scoring Guide:\n\n Task: As an evaluator, determine how well a tweet represents a business opportunity for the agent based on contextual relevance to the specific agent use case provided.\n\n IMPORTANT: Only score highly for needs that directly relate to the agent's specific use case. Similar but different problems should receive lower scores unless they specifically mention the agent's domain.\n\n Agent use case: Find people who needs SERP API service and is looking for cheaper options for scraping\n\n Scoring Criteria:\n\n Score 2 - No Business Opportunity:\n - Criteria: Tweet is completely unrelated to the agent's use case or shows no indication of need for the agent's specific offering\n - Context: Author is not expressing any pain point, question, or situation relevant to the agent's domain\n - Examples:\n - Agent Use Case: \"Find people needing SERP API services\"\n - Tweet: \"Just had amazing pizza for lunch!\" → Score 2 (completely unrelated)\n - Tweet: \"Our streaming API is having problems\" → Score 2 (different API domain)\n\n Score 5 - Potential Interest:\n - Criteria: Tweet shows indirect relevance to the agent's domain but lacks clear intent, urgency, or specific need\n - Context: Author mentions related topics but doesn't express explicit need for the agent's specific solution\n - Examples:\n - Agent Use Case: \"Find people needing SERP API services\"\n - Tweet: \"Working on a new web scraping project\" → Score 5 (related activity, no explicit SERP need)\n - Tweet: \"APIs are getting expensive these days\" → Score 5 (general API concern, not SERP-specific)\n\n Score 9 - Strong Business Opportunity:\n - Criteria: Tweet indicates a clear need, problem, or interest that directly aligns with the agent's specific use case\n - Context: Author is seeking solutions, expressing frustration, asking for recommendations, or describing challenges specifically in the agent's domain\n - Examples:\n - Agent Use Case: \"Find people needing SERP API services\"\n - Tweet: \"Anyone know a reliable API for Google search results? Current one keeps failing\" → Score 9 (direct SERP API need)\n - Tweet: \"SERP API costs are killing our budget, need alternatives\" → Score 9 (specific SERP API problem)\n \n Output Format:\n Score: [2, 5, or 9], Explanation: [Brief explanation focusing on how specifically this relates to the agent's use case and the level of expressed need]" }, "count": { "anyOf": [ { "type": "integer", "maximum": 200.0, "minimum": 10.0 }, { "type": "null" } ], "title": "Count", "description": "The number of results to return per source. Min 10. Max 200.", "default": 10 } }, "type": "object", "required": [ "prompt", "tools" ], "title": "ScraperStreamingSynapseRequest" }, "TikTokAuthor": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "12345" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Username", "example": "desearch" }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nickname", "example": "Desearch" }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "example": "https://example.com/avatar.jpg" }, "verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Verified", "example": true }, "following": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Following", "example": 1200 }, "followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Followers", "example": 50000 }, "heart": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Heart", "example": 300000 } }, "type": "object", "title": "TikTokAuthor" }, "TikTokComment": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "7620891413932166433" }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Videoid", "example": "7620891413932166433" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "example": "comment text" }, "createTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createtime", "example": "2024-01-15T11:00:00Z" }, "author": { "anyOf": [ { "$ref": "#/components/schemas/TikTokAuthor" }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Likes", "example": 42 }, "replies": { "items": { "type": "object" }, "type": "array", "title": "Replies" } }, "type": "object", "title": "TikTokComment" }, "TikTokMusic": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "67890" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "example": "Song Name" }, "authorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorname", "example": "Artist" } }, "type": "object", "title": "TikTokMusic" }, "TikTokPost": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "7620891413932166433" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "example": "https://www.tiktok.com/@tiktok/video/7620891413932166433" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "example": "caption text" }, "createTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createtime", "example": "2024-01-15T10:30:00Z" }, "author": { "anyOf": [ { "$ref": "#/components/schemas/TikTokAuthor" }, { "type": "null" } ] }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/TikTokStats" }, { "type": "null" } ] }, "music": { "anyOf": [ { "$ref": "#/components/schemas/TikTokMusic" }, { "type": "null" } ] }, "hashtags": { "items": { "type": "string" }, "type": "array", "title": "Hashtags" }, "mentions": { "items": { "type": "string" }, "type": "array", "title": "Mentions" }, "videoDuration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Videoduration", "example": 15000 }, "videoWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Videowidth", "example": 1080 }, "videoHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Videoheight", "example": 1920 }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thumbnailurl", "example": "https://example.com/thumb.jpg" }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mediaurl", "example": "https://example.com/video.mp4" } }, "type": "object", "title": "TikTokPost" }, "TikTokProfile": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "example": "12345" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Username", "example": "desearch" }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nickname", "example": "Desearch" }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "example": "https://example.com/avatar.jpg" }, "verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Verified", "example": true }, "following": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Following", "example": 1200 }, "followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Followers", "example": 50000 }, "heart": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Heart", "example": 300000 }, "bio": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bio", "example": "bio text" }, "videoCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Videocount", "example": 250 }, "digCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Digcount", "example": 450000 } }, "type": "object", "title": "TikTokProfile" }, "TikTokSearchRequest": { "properties": { "query": { "type": "string", "title": "Query", "description": "Keyword or phrase to search on TikTok", "example": "bittensor" }, "count": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Count", "description": "Number of results to return", "default": 10 }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor", "description": "Pagination cursor" }, "sort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sort", "description": "Sort option when supported" } }, "type": "object", "required": [ "query" ], "title": "TikTokSearchRequest" }, "TikTokStats": { "properties": { "playCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Playcount", "example": 120000 }, "digCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Digcount", "example": 5000 }, "commentCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Commentcount", "example": 120 }, "shareCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sharecount", "example": 45 }, "collectCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Collectcount", "example": 10 } }, "type": "object", "title": "TikTokStats" }, "TooManyRequestsResponse": { "properties": { "detail": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "object", "title": "Detail", "example": { "error_code": 429, "message": "Too Many Requests", "retry_after": "60 seconds" } } }, "type": "object", "required": [ "detail" ], "title": "TooManyRequestsResponse" }, "ToolEnum": { "type": "string", "enum": [ "web", "hackernews", "reddit", "wikipedia", "youtube", "twitter", "arxiv" ], "title": "ToolEnum" }, "TwitterScraperEntities": { "properties": { "hashtags": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperEntitiesSymbol" }, "type": "array" }, { "type": "null" } ], "title": "Hashtags in the tweet" }, "media": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperEntitiesMedia" }, "type": "array" }, { "type": "null" } ], "title": "Media attachments" }, "symbols": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperEntitiesSymbol" }, "type": "array" }, { "type": "null" } ], "title": "Cashtags/symbols" }, "timestamps": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Timestamp entities" }, "urls": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperEntityUrl" }, "type": "array" }, { "type": "null" } ], "title": "URLs in the tweet" }, "user_mentions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperEntitiesUserMention" }, "type": "array" }, { "type": "null" } ], "title": "Mentioned users" } }, "type": "object", "title": "TwitterScraperEntities" }, "TwitterScraperEntitiesMedia": { "properties": { "display_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Url", "example": "pic.twitter.com/example" }, "expanded_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expanded Url", "example": "https://twitter.com/user/status/123/photo/1" }, "id_str": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id Str", "example": "1234567890123456789" }, "indices": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Indices", "example": [ 100, 123 ] }, "media_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Key", "example": "3_1234567890123456789" }, "media_url_https": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Url Https", "example": "https://pbs.twimg.com/media/example.jpg" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media type: photo, video, or animated_gif", "example": "photo" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "example": "https://t.co/example" }, "additional_media_info": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaAdditionalInfo" }, { "type": "null" } ], "title": "Additional media information" }, "ext_media_availability": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaExtAvailability" }, { "type": "null" } ], "title": "External media availability status" }, "features": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaFeatures" }, { "type": "null" } ], "title": "Media features like face detection" }, "sizes": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaSizes" }, { "type": "null" } ], "title": "Available media sizes" }, "original_info": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaOriginalInfo" }, { "type": "null" } ], "title": "Original media information" }, "allow_download_status": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaAllowDownloadStatus" }, { "type": "null" } ], "title": "Download permission status" }, "video_info": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaVideoInfo" }, { "type": "null" } ], "title": "Video-specific information" }, "media_results": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaResults" }, { "type": "null" } ], "title": "Media result details" } }, "type": "object", "title": "TwitterScraperEntitiesMedia" }, "TwitterScraperEntitiesMediaAdditionalInfo": { "properties": { "monetizable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Monetizable", "example": true }, "source_user": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Source User", "example": {} } }, "type": "object", "title": "TwitterScraperEntitiesMediaAdditionalInfo" }, "TwitterScraperEntitiesMediaAllowDownloadStatus": { "properties": { "allow_download": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Allow Download", "example": true } }, "type": "object", "title": "TwitterScraperEntitiesMediaAllowDownloadStatus" }, "TwitterScraperEntitiesMediaExtAvailability": { "properties": { "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "example": "available" } }, "type": "object", "title": "TwitterScraperEntitiesMediaExtAvailability" }, "TwitterScraperEntitiesMediaFeature": { "properties": { "faces": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Rect" }, "type": "array" }, { "type": "null" } ], "title": "Detected faces in media", "example": [] } }, "type": "object", "title": "TwitterScraperEntitiesMediaFeature" }, "TwitterScraperEntitiesMediaFeatures": { "properties": { "large": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaFeature" }, { "type": "null" } ], "title": "Features for large size" }, "medium": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaFeature" }, { "type": "null" } ], "title": "Features for medium size" }, "small": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaFeature" }, { "type": "null" } ], "title": "Features for small size" }, "orig": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaFeature" }, { "type": "null" } ], "title": "Features for original size" } }, "type": "object", "title": "TwitterScraperEntitiesMediaFeatures" }, "TwitterScraperEntitiesMediaOriginalInfo": { "properties": { "height": { "type": "integer", "title": "Height", "example": 1080 }, "width": { "type": "integer", "title": "Width", "example": 1920 }, "focus_rects": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Rect" }, "type": "array" }, { "type": "null" } ], "title": "Focus Rects", "example": [] } }, "type": "object", "required": [ "height", "width" ], "title": "TwitterScraperEntitiesMediaOriginalInfo" }, "TwitterScraperEntitiesMediaResult": { "properties": { "media_key": { "type": "string", "title": "Media Key", "example": "3_1234567890123456789" } }, "type": "object", "required": [ "media_key" ], "title": "TwitterScraperEntitiesMediaResult" }, "TwitterScraperEntitiesMediaResults": { "properties": { "result": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaResult" }, { "type": "null" } ], "title": "Media result details" } }, "type": "object", "title": "TwitterScraperEntitiesMediaResults" }, "TwitterScraperEntitiesMediaSizes": { "properties": { "large": { "anyOf": [ { "$ref": "#/components/schemas/MediaSize" }, { "type": "null" } ], "title": "Large size dimensions" }, "medium": { "anyOf": [ { "$ref": "#/components/schemas/MediaSize" }, { "type": "null" } ], "title": "Medium size dimensions" }, "small": { "anyOf": [ { "$ref": "#/components/schemas/MediaSize" }, { "type": "null" } ], "title": "Small size dimensions" }, "thumb": { "anyOf": [ { "$ref": "#/components/schemas/MediaSize" }, { "type": "null" } ], "title": "Thumbnail size dimensions" } }, "type": "object", "title": "TwitterScraperEntitiesMediaSizes" }, "TwitterScraperEntitiesMediaVideoInfo": { "properties": { "duration_millis": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Video duration in milliseconds", "example": 30000 }, "aspect_ratio": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Aspect Ratio", "example": [ 16, 9 ] }, "variants": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperEntitiesMediaVideoInfoVariant" }, "type": "array" }, { "type": "null" } ], "title": "Available video quality variants" } }, "type": "object", "title": "TwitterScraperEntitiesMediaVideoInfo" }, "TwitterScraperEntitiesMediaVideoInfoVariant": { "properties": { "content_type": { "type": "string", "title": "Content Type", "example": "video/mp4" }, "url": { "type": "string", "title": "Url", "example": "https://video.twimg.com/example.mp4" }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bitrate", "example": 2176000 } }, "type": "object", "required": [ "content_type", "url" ], "title": "TwitterScraperEntitiesMediaVideoInfoVariant" }, "TwitterScraperEntitiesSymbol": { "properties": { "indices": { "items": { "type": "integer" }, "type": "array", "title": "Indices", "example": [ 0, 5 ] }, "text": { "type": "string", "title": "Text", "example": "AAPL" } }, "type": "object", "required": [ "indices", "text" ], "title": "TwitterScraperEntitiesSymbol" }, "TwitterScraperEntitiesUserMention": { "properties": { "id_str": { "type": "string", "title": "Id Str", "example": "123456789" }, "name": { "type": "string", "title": "Name", "example": "John Doe" }, "screen_name": { "type": "string", "title": "Screen Name", "example": "johndoe" }, "indices": { "items": { "type": "integer" }, "type": "array", "title": "Indices", "example": [ 0, 10 ] } }, "type": "object", "required": [ "id_str", "name", "screen_name", "indices" ], "title": "TwitterScraperEntitiesUserMention" }, "TwitterScraperEntityUrl": { "properties": { "display_url": { "type": "string", "title": "Display Url", "example": "example.com" }, "expanded_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expanded Url", "example": "https://example.com/full-url" }, "url": { "type": "string", "title": "Url", "example": "https://t.co/short" }, "indices": { "items": { "type": "integer" }, "type": "array", "title": "Indices", "example": [ 50, 73 ] } }, "type": "object", "required": [ "display_url", "url", "indices" ], "title": "TwitterScraperEntityUrl" }, "TwitterScraperExtendedEntities": { "properties": { "media": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperEntitiesMedia" }, "type": "array" }, { "type": "null" } ], "title": "Extended media information for multiple attachments" } }, "type": "object", "title": "TwitterScraperExtendedEntities" }, "TwitterScraperMedia": { "properties": { "media_url": { "type": "string", "title": "Media Url", "default": "", "example": "https://pbs.twimg.com/media/example.jpg" }, "type": { "type": "string", "title": "Type", "default": "", "example": "photo" } }, "type": "object", "title": "TwitterScraperMedia" }, "TwitterScraperTweet": { "properties": { "user": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperUser" }, { "type": "null" } ] }, "id": { "type": "string", "title": "Id", "example": "987654321" }, "text": { "type": "string", "title": "Text", "example": "This is an example tweet." }, "reply_count": { "type": "integer", "title": "Reply Count", "example": 10 }, "view_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "View Count", "example": 1000 }, "retweet_count": { "type": "integer", "title": "Retweet Count", "example": 5 }, "like_count": { "type": "integer", "title": "Like Count", "example": 100 }, "quote_count": { "type": "integer", "title": "Quote Count", "example": 2 }, "bookmark_count": { "type": "integer", "title": "Bookmark Count", "example": 3 }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "example": "https://twitter.com/example_tweet" }, "created_at": { "type": "string", "title": "Created At", "example": "2023-01-01T00:00:00Z" }, "media": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperMedia" }, "type": "array" }, { "type": "null" } ], "title": "Media", "example": [] }, "is_quote_tweet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Quote Tweet", "example": false }, "is_retweet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Retweet", "example": false }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tweet language code", "example": "en" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation thread ID", "example": "987654321" }, "in_reply_to_screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Username being replied to", "example": "someuser" }, "in_reply_to_status_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tweet ID being replied to", "example": "987654320" }, "in_reply_to_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User ID being replied to", "example": "123456789" }, "quoted_status_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quoted tweet ID", "example": "987654319" }, "quote": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperTweet" }, { "type": "null" } ], "title": "Quoted tweet object" }, "replies": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperTweet" }, "type": "array" }, { "type": "null" } ], "title": "Reply tweets" }, "display_text_range": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Text display range indices", "example": [ 0, 280 ] }, "entities": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperEntities" }, { "type": "null" } ], "title": "Tweet entities (hashtags, URLs, mentions)" }, "extended_entities": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperExtendedEntities" }, { "type": "null" } ], "title": "Extended entities for media" }, "retweet": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperTweet" }, { "type": "null" } ], "title": "Retweeted tweet object. Available for user posts endpoint only." } }, "type": "object", "required": [ "id", "text", "reply_count", "retweet_count", "like_count", "quote_count", "bookmark_count", "created_at" ], "title": "TwitterScraperTweet" }, "TwitterScraperUser": { "properties": { "id": { "type": "string", "title": "Id", "example": "123456789" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "example": "https://twitter.com/example_user" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "example": "John Doe" }, "username": { "type": "string", "title": "Username", "example": "johndoe" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "example": "2023-01-01T00:00:00Z" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "example": "This is an example user description." }, "favourites_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Favourites Count", "example": 100 }, "followers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Followers Count", "example": 1500 }, "followings_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Followings Count", "example": 100 }, "listed_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Listed Count", "example": 10 }, "media_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Media Count", "example": 50 }, "profile_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Profile Image Url", "example": "https://example.com/profile.jpg" }, "profile_banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Profile Banner Url", "example": "https://example.com/banner.jpg" }, "statuses_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Statuses Count", "example": 500 }, "verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Verified", "example": true }, "is_blue_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Indicates if the user is Blue Tick verified", "example": true }, "entities": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperUserEntities" }, { "type": "null" } ], "title": "User profile entities" }, "can_dm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Indicates if the user has enabled DMs", "example": true }, "can_media_tag": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Indicates if the user can be tagged in media", "example": true }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User location", "example": "Jamaica" }, "pinned_tweet_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Pinned Tweet Ids", "example": [ "123456789", "987654321" ] }, "professional": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperUserProfessional" }, { "type": "null" } ], "title": "Professional information" } }, "type": "object", "required": [ "id", "username" ], "title": "TwitterScraperUser" }, "TwitterScraperUserEntities": { "properties": { "description": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperUserEntitiesDescription" }, { "type": "null" } ], "title": "Entities in user description" }, "url": { "anyOf": [ { "$ref": "#/components/schemas/TwitterScraperUserEntitiesDescription" }, { "type": "null" } ], "title": "Entities in user profile URL" } }, "type": "object", "title": "TwitterScraperUserEntities" }, "TwitterScraperUserEntitiesDescription": { "properties": { "urls": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TwitterScraperEntityUrl" }, "type": "array" }, { "type": "null" } ], "title": "URLs in user description or profile" } }, "type": "object", "title": "TwitterScraperUserEntitiesDescription" }, "TwitterScraperUserProfessional": { "properties": { "professional_type": { "type": "string", "title": "Professional Type", "example": "Business" }, "category": { "items": { "$ref": "#/components/schemas/TwitterScraperUserProfessionalCategory" }, "type": "array", "title": "Professional categories" } }, "type": "object", "required": [ "professional_type" ], "title": "TwitterScraperUserProfessional" }, "TwitterScraperUserProfessionalCategory": { "properties": { "id": { "type": "integer", "title": "Id", "example": 1 }, "name": { "type": "string", "title": "Name", "example": "Technology" } }, "type": "object", "required": [ "id", "name" ], "title": "TwitterScraperUserProfessionalCategory" }, "UnauthorizedResponse": { "properties": { "detail": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "object", "title": "Detail", "example": { "error_code": 401, "message": "Unauthorized", "reason": "Invalid API key" } } }, "type": "object", "required": [ "detail" ], "title": "UnauthorizedResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WebSearchResponse": { "properties": { "youtube_search_results": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebSearchResultItem" }, "type": "array" }, { "type": "null" } ], "title": "Youtube Search Results", "description": "Youtube search results" }, "hacker_news_search_results": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebSearchResultItem" }, "type": "array" }, { "type": "null" } ], "title": "Hacker News Search Results", "description": "Hacker News search results" }, "reddit_search_results": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebSearchResultItem" }, "type": "array" }, { "type": "null" } ], "title": "Reddit Search Results", "description": "Reddit search results" }, "arxiv_search_results": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebSearchResultItem" }, "type": "array" }, { "type": "null" } ], "title": "Arxiv Search Results", "description": "Arxiv search results" }, "wikipedia_search_results": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebSearchResultItem" }, "type": "array" }, { "type": "null" } ], "title": "Wikipedia Search Results", "description": "Wikipedia search results" }, "search_results": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebSearchResultItem" }, "type": "array" }, { "type": "null" } ], "title": "Search Results", "description": "Search results" } }, "type": "object", "required": [ "youtube_search_results", "hacker_news_search_results", "reddit_search_results", "arxiv_search_results", "wikipedia_search_results", "search_results" ], "title": "WebSearchResponse" }, "WebSearchResultItem": { "properties": { "title": { "type": "string", "title": "Title", "description": "EXCLUSIVE Major coffee buyers face losses as Colombia ..." }, "snippet": { "type": "string", "title": "Snippet", "description": "Coffee farmers in Colombia, the world's No. 2 arabica producer, have failed to deliver up to 1 million bags of beans this year or nearly 10% ..." }, "link": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Link", "description": "https://www.reuters.com/world/americas/exclusive-major-coffee-buyers-face-losses-colombia-farmers-fail-deliver-2021-10-11/" } }, "type": "object", "required": [ "title", "snippet", "link" ], "title": "WebSearchResultItem" }, "WebSearchResultsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebSearchResultItem" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "WebSearchResultsResponse" }, "WebToolEnum": { "type": "string", "enum": [ "web", "hackernews", "reddit", "wikipedia", "youtube", "arxiv" ], "title": "WebToolEnum" }, "XLinksSearchResponse": { "properties": { "miner_tweets": { "items": { "$ref": "#/components/schemas/TwitterScraperTweet" }, "type": "array", "title": "Miner Tweets", "description": "Miner tweets" } }, "type": "object", "required": [ "miner_tweets" ], "title": "XLinksSearchResponse" }, "XRetweetersResponse": { "properties": { "users": { "items": { "$ref": "#/components/schemas/TwitterScraperUser" }, "type": "array", "title": "Users" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for pagination" } }, "type": "object", "required": [ "users" ], "title": "XRetweetersResponse" }, "XTrendItem": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the trending topic" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "The search query associated with the trend" }, "rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rank", "description": "The rank of the trend" } }, "type": "object", "required": [ "name" ], "title": "XTrendItem" }, "XTrendsResponse": { "properties": { "trends": { "items": { "$ref": "#/components/schemas/XTrendItem" }, "type": "array", "title": "Trends", "description": "List of trending topics" }, "woeid": { "anyOf": [ { "$ref": "#/components/schemas/XTrendsWoeid" }, { "type": "null" } ], "description": "The location for which trends were retrieved" } }, "type": "object", "required": [ "trends" ], "title": "XTrendsResponse" }, "XTrendsWoeid": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the location" }, "id": { "type": "integer", "title": "Id", "description": "The WOEID (Where On Earth ID) of the location" } }, "type": "object", "required": [ "name", "id" ], "title": "XTrendsWoeid" }, "XUserPostsResponse": { "properties": { "user": { "$ref": "#/components/schemas/TwitterScraperUser" }, "tweets": { "items": { "$ref": "#/components/schemas/TwitterScraperTweet" }, "type": "array", "title": "Tweets" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for pagination" } }, "type": "object", "required": [ "user", "tweets" ], "title": "XUserPostsResponse" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization" } } }, "security": [ { "ApiKeyAuth": [] } ], "servers": [ { "url": "https://api.desearch.ai" } ] }